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Notice 


Apple Computer, Inc. reserves the right to make improvements in the 
product described in this manual at any time and without notice. 


Disclaimer of All Warranties and Liabilities 


Apple Computer, Inc. makes no warranties, either express or implied, with 
respect to this manual or with respect to the software described in this 
manual, its quality, performance, merchantability, or fitness for any 
particular purpose. Apple Computer, Inc. software is sold or licensed ‘“‘as 
is.”’ The entire risk as to its quality and performance is with the buyer. 
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(and not Apple Computer, Inc., its distributor, or its retailer) assumes the 
entire cost of all necessary servicing, repair, or correction and any 
incidental or consequential damages. In no event will Apple Computer, Inc. 
be liable for direct, indirect, incidental, or consequential damages resulting 
from any defect in the software, even if Apple Computer, Inc. has been 
advised of the possiblity of such damages. Some states do not allow the 
exclusion or limitation of implied warranties or liability for incidental or 
consequential damages, so the above limitation or exclusion may not apply 
to you. 


This manual is copyrighted. All rights are reserved. This document may 
not, in whole or part, be copied, photocopied, reproduced, translated or 
reduced to any electronic medium or machine readable form without prior 
consent, in writing, from Apple Computer, Inc. 
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About This Manual 


This is a reference manual for the Applesoft BASIC programming 
language as implemented on the Apple Ile computer. It is intended for 
readers who have had some previous experience with programming, 
either in BASIC or in some other programming language. It assumes 
that you are familiar with the material in the Apple Ile Owner's Man- 
ual, and if you are a novice programmer, that you have read the Apple 
lle Applesoft Tutorial. 


To make using this manual easier for you, we have divided it into two 
volumes. The complete table of contents, chapters one through eight, 
and the complete index appear in volume one, the volume you are 
now reading. Volume two holds the appendices and the glossary; the 
index is also included in this volume for your convenience. 


Purposes of This Manual 


This manual has four purposes: 


@ Toserve as acomplete reference manual to the Applesoft BASIC 
language for the experienced programmer. 


@ To provide clear enough explanations and examples so that a 
new programmer can learn the details of any statement quickly 
and easily. 


@ To allow any reader, even one who is not trying to learn Applesoft 
in detail, to get a general feel for the language. 


@ To provide an introduction to program planning, design, and de- 
velopment for the programmer-in-training. 


This manual is decidedly not a tutorial. Experienced programmers 
can learn a great deal about Applesoft by reading it from the first 
page straight through to the end; but it wasn't designed to be used in 
that way. 
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Where to Learn More 


Xiv 


The following sources contain further information about the Apple lle 
computer in general and the Applesoft programming language in 
particular: 


@ The Apple Ile Owner’s Manual covers the basics of the system 
and includes a special section on the Apple Ile’s keyboard. It 
also contains a list of books and magazines of special interest to 
Applesoft programmers, as well as a short guide to the rest of 
the extensive documentation that comes with your Apple lle. 


@e APPLE PRESENTS...APPLE is a training disk that comes 
with all disk-based Apple Ile systems. It contains an interactive 
tutorial program giving you hands-on practice with many of 
the concepts discussed in the Apple Ile Owner's Manual. It's a 
must if you're new to computers. 


@ The Apple lle App/esoft Tutorial is an excellent guide for be- 
ginning programmers. It provides introductory, step-by-step 
guidance for the new programmer and has a special chapter on 
editing Applesoft programs. 


@ Apple Backpack: Humanized Programming in BASIC, oy Scot 
Kamins and Mitchell Waite (BYTE/McGraw-Hill Books) fills the 
gap some newer programmers may feel between the Applesoft 
Tutorial and this reference manual. It teaches programming ina 
friendly and easy-paced way for people who are not computer 
experts. 


@ The Apple Ile Reference Manual contains a wealth of informa- 
tion about the more technical aspects of the system's operation, 
with lists of various programmer-accessible system flags, point- 
ers, and soft switches. 


How This Manual Is Organized 


This manual has 8 chapters, 14 appendices, a glossary of terms, an 

index, and a quick reference card. All of it is designed to help you get 
the most out of Applesoft. Here’s a description of what each chapter 

and appendix is about: 


Chapter 1, “General Information,” contains information every Apple- 
soft programmer needs. It discusses the programming environment 
in which Applesoft operates and tells how to create, modify, execute, 
and store Applesoft programs. 
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Chapter 2, “Variables and Arithmetic,” deals with some of the most 
fundamental concepts of Applesoft programming: variables, arithme- 
tic expressions and operators, arithmetic precedence, Applesoft’s 
built-in functions, and how to define and use your own functions. 


Chapter 3, “Control,” covers the various statements available to di- 
rect the flow of program execution. It includes information on uncon- 
ditional and conditional branching, loops, subroutines, error handling, 
and program termination. 


Chapter 4, “Arrays and Strings,” completes the material on variables 
begun in Chapter 2. It includes information on the definition and use 
of arrays in Applesoft and on the various string manipulation facilities. 


Chapter 5, “Input/Output,” describes Applesoft’s facilities for getting 
information into and out of programs and for formatting the way infor- 
mation is presented on the display screen. 


Chapter 6, “Graphics,” tells how to create, change, display, and store 
low- and high-resolution graphic designs. There is an extensive dis- 
cussion on creating and using shape tables, as well as examples of 
how to create animation Sequences. 


Chapter 7, “Utility Statements,” contains information on a variety 
of miscellaneous Applesoft facilities for low-level control of the 
programming environment: directly accessing specific memory 
locations, controlling the limits of program space, and tracing the 
execution of a program for debugging purposes. 


Chapter 8, “Bringing It All Together,” is more tutorial than any other 
chapter in the manual; it describes and demonstrates a method for 
planning, designing, and developing efficient, bug-free (well, re/a- 
tively bug-free) programs. 


Appendix A, “Summary of Applesoft Statements and Functions,” 
gives an abbreviated description of each Applesoft statement and 
function, together with a reference to the chapter, section, or appen- 
dix where you can find more detailed information and examples. 


Appendix B, “Syntax Definitions,” defines terms used in the formal 
syntactic definitions of Applesoft statements given in Appendix A. In 
the body of the manual, statement syntax is shown by example rather 
than by formal definition; most readers can safely avoid the formal 
definitions altogether. 
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Appendix C, “ASCII Character Codes,” contains a complete listing of 
the ASCII characters; it is an adjunct to the comments on ASCII in 
chapter 4. 


Appendix D, “Reserved Words,’ is a list of words (some of them 
rather odd-looking) that cannot be used in variable names. 


Appendix E, “Error Messages,” describes the meanings of the error 
messages that Applesoft displays on the screen. Each description in- 
cludes an explanation of why the error occured; in some cases, there 
are suggestions for debugging. 


Appendix F, “Peeks, Pokes, and Calls,” deals with low-level access 
to features of the Apple Ile computer via Applesoft’s PEEK function 
and POKE and CALL statements. There are sections on screen 
text, the keyboard, graphics, miscellaneous input and output, and 
error handling. 


Appendix G, “Hints for Program Efficiency,” offers techniques for 
cutting down the size of programs and for speeding up program 
execution. 


Appendix H, “Implementation Details,” contains information of inter- 
est mainly to the advanced programmer. Included here is a memory 
map with a list of pointers and their descriptions, information on 
Applesoft’s methods of internal storage allocation, an outline of its 
usage of special locations in page © of memory, and a list of the 
tokens it uses for internal representation of keywords. 


Appendix |, “Display Formats for Numbers,” describes how Applesoft 
displays numbers on the screen and gives the ranges of numbers the 
system is capable of handling. 


Appendix J, “On-Screen Editing and Cursor Control,” contains tables 
summarizing Applesoft’s on-screen editing features. 


Appendix K, “40/80-Column Differences,” is a table showing the dif- 
ferences in Applesoft’s behavior with and without the optional Apple 
Ile 80-Column Text Card installed. 


Appendix L, “Comparison with Integer BASIC,” gives charts showing 
the differences between Applesoft and Apple Integer BASIC and 
discusses how to convert Integer BASIC and non-Apple-lIle BASIC 
programs into Applesoft. 
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Appendix M, “If You Have a Cassette Recorder,’ describes Apple- 
soft’s statements for using tape cassettes as a storage medium for 
programs and information. 


Appendix N, “Complete Listing of the Postage Rates Program,” 
gives the complete text of the programming example developed in 
Chapter 8. 


At the back of the manual is a Glossary of technical terms. In general, 
buzz words are no-no’s in this manual; but any technical field has its 
own jargon, developed out of necessity to describe concepts genu- 
inely having no parallel in common language. The glossary lists all 
(we hope!) such words and terms that have found their way into the 
manual, and a few others besides. 


A tear-out Quick Reference Card, designed to act as a “memory jog, 
gives an extremely brief description of each statement, function, op- 
erator, and variable type. 


How to Use This Manual 


Here are some suggestions on how to use this manual, depending on 
the particular goals you are trying to accomplish. 





As a Reference 


@ Look up the feature of interest on the Quick Reference Card; 
each statement, function, operator, and variable type is listed 
there in an extremely abbreviated form as a “memory jog.” 


@ Look up the feature in Appendix A, “Summary of Applesoft State- 
ments and Functions”; each statement and function is described 
briefly, and a reference is given to the chapter, section, or appen- 
dix where it is discussed in detail. 


@ Look up the feature in the index; there you'll find references to 
the places in the manual where it is mentioned. 


@ Look inthe appendices atthe back of the manual for quick refer- 
ence on specific facts. 
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To Learn the Applesoft Language 


Read Appendix A, “Summary of Statements and Functions,” to 
get a quick feel for each of the features in the language. 


Read through each chapter and enter and run the example pro- 
grams; then try modifying them to check your understanding and 
gain hands-on experience. 


Enter, run, and modify the example program in chapter 8. 





To Learn Program Planning 


Read through chapter 8 and experiment with the program devel- 
oped there. 


Develop your own programs based on the methods presented in 
chapter 8. 


Restructure someone else’s program using the methods of 
chapter 8. 


Read Appendix G, “Hints for Program Efficiency,” at the back of 
the manual. 





Conventions Used in This Manual 


Throughout this manual you'll encounter the following conventions: 


Warning 

Warning boxes contain vital information about potentially dangerous 
situations in which you can damage or destroy equipment, programs, 
or information. 


Grey boxes contain minor details, tricky points, side comments, helpful 
hints, historical notes, and other information of secondary importance. 


Screen boxes represent information as it will 
aPPear on the computer‘’s display screen, 


Throughout the manual, extensive use has been made of marginal 
notes for key points, definitions, and cross-references. After reading 


a 


chapter or section, you can use the marginal notes to review what 


you've learned or to refer back to a particular point for quick 
reference. 
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New terms being introduced for the first time are set in italics; defini- 
tions for most such terms can be found in the marginal notes, the 
Glossary, or both. 


Numbers (Such as memory addresses) preceded by a dollar sign, 
such as $9600, are expressed in hexadecimal; numbers without a 
dollar sign are generally in decimal, unless otherwise stated. 
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BASIC: Beginner's All-purpose Symbolic 
Instruction Code 


ANSI: American National Standards 
Institute 


creating and modifying programs: see 
Section 1.1 


operations on whole programs: see 
Section 1.2 


interrupting and resuming: see Sec- 
tion 1.3 


on-screen editing: see Section 1.4 


1.1 


program line: the basic unit of an Apple- 
soft program 


statement: a unit of a program specify- 
ing an action for the computer to perform 


General Information 


Applesoft BASIC is a very extended version (in computer parlance, 
a superset) of the BASIC programming language. It includes many 
more features than either the original BASIC, developed at Dart- 
mouth College in the 1960s, or the standard version of the language, 
as defined by the American National Standards Institute (ANSI). The 
extra features allow your programs to use the special capabilities of 
the Apple Ile, such as color graphics, animation, and hand controls. 


This first chapter introduces the Applesoft language and the environ- 
ment in which it operates. Here you will find information on how to 
create, modify, execute, and store Applesoft programs. 


Section 1.1, “Statements and Lines,” deals with the fundamental 
units of Applesoft programs. It tells how to type Applesoft statements 
for immediate execution and how to create and modify programs in 
the computer's memory. 


Section 1.2, “Operations on Whole Programs,’ introduces Apple- 
soft’s commands for displaying a program on the screen, writing it to 
an output device such as a printer, executing it, saving it on a disk, 
and retrieving it from a disk. 


Section 1.3, “Interrupting and Resuming a Program,’ tells how to 
suspend or cancel the execution of a running program and how to re- 
sume execution after an interruption. 


Section 1.4, “Editing What You Type,” briefly describes Applesoft’s 
facilities for correcting typing errors and editing text on the screen. 


Statements and Lines 


The basic unit of an Applesoft program is the program line, which 
may contain one or more statements specifying actions you want the 
computer to perform. Most Applesoft statements are identified by 
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deferred execution: see Section 1.1.2 


Use while typing Apple- 


soft programs 


80-Column Text Card: see Apple /le 
Owner's Manual, Apple Ile 80-Column 
Text Card Manual 


Program lines may be up to 239 charac- 
ters long 


PIX INT statement: see Section 5.2.2 





one or more keywords, special words that Applesoft recognizes as 
denoting a particular type of statement. 


You can type a program line whenever you see Applesoft’s prompt 
character, aright bracket (1), displayed on the screen followed by 
the cursor. Each line you type must end in a press of the [ RETURN |] 
key (but see Section 1.1.4 about multiple statements per line). De- 
pending on what you type, the statements in the line may either be 
executed immediately or deferred for later execution as part of a 
complete program. 


Applesoft understands only uppercase letters. Most programmers 
therefore keep the key down while typing programs. 


Notice that a program line is not the same thing as a line of text on the 
screen. If the cursor reaches the end of a screen line while you're typ- 
ing aprogram line, it will “wrap around” to the beginning of the next 
screen line and continue displaying what you type. Although the 
screen is only 40 columns wide (or 80 if you're using the Apple Ile 80- 
Column Text Card), a program line may be up to 239 characters long 


and ends only when you press the key. 


Actually, you can type as many as 255 characters in a program line, but 
all characters after 239 will be ignored. If you type more than 255 char- 
acters, Applesoft will display a backslash character (\) and cancel the 
entire line. It will then redisplay the prompt character (J ) followed by the 
cursor, and you will have to retype the entire line from the beginning. As 
a warning, Applesoft will “beep” the computer's built-in speaker with 
every character you type beginning with the 245th in a line. 


It’s usually a bad idea to type program lines this long. In practice, you 
should keep your lines well below 239 characters in length. 





Immediate Execution 


If you want Applesoft to execute a program line as soon as you type 
it, just type the line and press the | RETURN | key. For example, if you 


type 
PRINT "HELLO" 


Applesoft immediately displays the word HEL.L.Q on the screen, on 
the line following what you just typed. 


General Information 





line number: a number identifying a line 
in an Applesoft program 


Maximum line number is 63999 


program: a sequence of program lines, 
each with a different line number 


Program lines automatically sorted into 
proper sequential order 


Leave intervals between line numbers 


1.1.4 


Colons separate multiple statements 


Line Numbers and Deferred Execution 


lf you want Applesoft to save a program line to be executed later— 
that is, if you want it to defer execution—then precede the line with a 
line number: 

10 PRINT “HELLO”® — 10 is the line number 

Line numbers must be in the range ® through 63555. Applesoft 
uses the presence or absence of line numbers to determine whether 
the line you type is to be carried out immediately or deferred (stored 


for execution at some future time). 


A sequence of deferred-execution lines, each preceded by a differ- 
ent line number, is an Applesoft program. Program lines are stored in 
the computer’s memory in sequential order, from the lowest-num- 
bered line to the highest. 





Adding Lines toa Program 


To add a new line to a program, just type the new line preceded by a 
line number indicating where in the program you wish to insert it. It 
makes no difference in what order you enter program lines; Applesoft 
will put them in the proper sequential order for you. 


Helpful Hint: Instead of using consecutive line numbers (0, 1, 2,...), 
it's usually more convenient to leave intervals of 5 or 10 or 20 between 
the line numbers in your program. This makes it easy to insert new lines, 
if necessary, in between the old ones. 





Multiple Statements on the Same Line 


Applesoft allows you to put more than one statement on the same 

program line. Use acolon (:) to separate the statements: 

40 PRINT "COME OUTSIDE" : 
{ &\ Viol 


PRINT “AND 


You can type as many statements as will fit within the limit of 239 
characters per line. 


Line Numbers and Deferred Execution 








Multiple statements make editing more 
difficult (although they speed up program 
execution) 


DEL deletes lines from the program in 
memory 


Deleting a single line 


Although using multiple statements on the same line can speed up the 
execution of your program, it can also make program editing difficult and 
time-consuming. The example above, for instance, has two statements 
on the same line. In order to change the word OUTSIDE in the first 
statement to INSIDE, you would have to retype both statements. But 
if each statement were on its own line, you would have to retype only 

the one statement you want to change. This may not seem like much 

of a time saving; but when you multiply three or four seconds by the 
hundreds of edits you might need to make in developing a typical pro- 
gram, the savings can become considerable. 





Deleting Lines from a Program: 
The DEL Command 


DEL 100+ 200 


The DEL command deletes (removes) a range of consecutive lines 
from the program currently in memory. The line numbers of the first 
and last lines to be deleted follow the keyword DEL. and are sepa- 
rated from each other by acomma. All program lines between the two 
specified line numbers, inclusive, are deleted from the program. The 
example above, for instance, will delete all lines from 100 to 200, 
inclusive. 


lf either line number is out of the range of lines in the actual program 
(for instance, ifthe commandisDEL 100% 200 andthe highest 
existing line number is i 3), then all existing lines within the speci- 
fied range are deleted. If DEL specifies a range of lines that doesn't 
exist, or if the second line number is smaller than the first, the com- 
mand has no effect: 

DEL 200% 100 —nothing happens 

A single number with a comma also has no effect: 

DEL Jas —nada pasa 

A single number without a comma Is a syntax error: 


VER 2o —syntax error 


To delete a single line from the program, simply type the number of 
that line and press | RETURN |: 


130 —press the key after 


you type the line number 


General Information 





Dash not allowed in DEL command 


__ IST command: see Section 1.2.3 


REM is for including explanatory 
remarks to a human reader 


If you're fond of redundancy, youcanalsouseDEL 130,+150to 
do the same thing. 


Unlike the L. I ST command, you cannot use a dash (-) to separate the 
line numbers in the DEL. command: 


DEL 60 - i100 —causes a syntax error 


The DEL command is normally used in immediate execution. You can 
also use it from within a program, but as soon as it is executed the pro- 
gram will stop with no error message: 


20 DEL 133, 230 —lines 133 through 230 re- 
moved from program; program 
execution halts 





Changing Lines ina Program 


To alter or replace an existing line of your program, simply type the 
new line using the same line number as the existing one. What you 
type will replace the old line under the same line number; the old line 
will be forgotten. 





Annotating a Program: The kk = Statement 
REM TEST FOR ERROR 


One rule of good programming practice is to include comments in 
your program, explaining or clarifying to ahuman reader how the pro- 
gram works. Applesoft’s kX EM statement allows you to include such 
remarks within the body of your program. It consists of the keyword 
REM (for “remark”) followed by any explanatory notes you care to in- 
clude. For example, 


O REM MONTHLY BUDGET PROGRAM 


Line Numbers and Deferred Execution 





_ IST command: see Section 1.2.3 


XUN command: see Section 1.2.4 


1.2 


NEkl command: see Section 1.2.1 


CLEAR command: see Section 1.2.2 


L IST command: see Section 1.2.3 


XUN command: see Section 1.2.4 


SAVE command: see Section 1.2.5 


LOAD command: see Section 1.2.6 





This statement is included in the program strictly for the benefit of the 
human reader. When you list the program, the REM statement will 
appear just like any other statement. But when you run the program, 
Applesoft will ignore the XE M statement and just go on to the next 
line. Everything following the keyword REM on the same line will be 
ignored. See Chapter 8, “Bringing It All Together,” for some tips on 
the use of the REM statement. 


Operations on Whole Programs 

This section describes Applesoft’s commands for manipulating 
whole programs: 

@ NEW clears the current program from the computer's memory so 


you can start typing another. 


@e CLEAR resets all variables and internal control information to 
their initial settings without affecting the Applesoft program in 
memory. 


@ LIST displays the current program on the screen or writes it to 
an output device such as a printer. 


@ UN executes the program currently in memory. It can also be 
used to load and execute a program stored on a disk. 


@ SAVE writes the program currently in memory onto a disk ora 
tape cassette for future use. 


@e OAD reads a program into memory from a disk or a tape cas- 
sette for execution. 


You can use all of these commands for immediate execution; you can 
use some of them from within your Applesoft programs as well. 


General Information 





1.2.1 


NE ll clears memory for anew program 


variables: see Section 2.1 


NEW in deferred execution 


hang: for a program to “spin its wheels” 
indefinitely, performing no useful work 


null string: a string containing no 
characters 


CLEAR in deferred execution 


1.2.2 


The NEW Command 
NEW 





The NEld command clears the current program from memory, resets 
the values of all numeric variables to © and those of all string vari- 
ables to the null string, and prepares Applesoft to accept a new pro- 
gram. If there are no program and no variables in memory, NE has 
no effect. 


Although NE ld is usually used in immediate execution, you can also 
use it in deferred execution (from within a program): 


1900 IF At = "RATS" THEN NEW 

—NEW in conditional statement 
999 NEW —NEW on its own line 
Warning 


Using NE in deferred execution can do strange and unpredictable 
things to Applesoft’s innards, causing subsequently entered programs 
to hang. If you use NEW from within a program, it’s a good idea to warn 
your user to restart the system before typing another program: 


100 IF AS = "RATS" THEN PRINT 
“PLEASE RESTART YTUOUUN SYSTEM 
BEFORE TYPING A NEW PROGRAM." : NEW 





The CLEAR Command 
CLEAR 


The CLEAR command resets the values of all numeric variables to © 
and those of all string variables to the null string; it also resets Apple- 
soft’s internal control information to its initial state. It has no effect on 
the program lines in memory. 


Although CLEAR is usually used in immediate execution, you can 
also use it in deferred execution (from within a program): 


i900 IF 24 = "NUTS" THEN CLEAR 
—CLEAR in conditional 

statement 
999 CLEAR —CLEAR onits ownline- 
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A 


subroutines, control stack: see 
Section 3.4 


FOR/NEXT loops: see Section 3.3 


1.2.3 


LIST displays or prints a program 


Pl} # statement: see Section 5.2.1 


Listing the entire program 


Listing a portion of the program 





Wa 


rning 





Be careful where you execute CLEAR. Since CLEAR resets Apple- 
soft’s internal control stack, using it in the midst of a subroutine or ina 
F OR/NE XT loop can interfere with the orderly flow of program execu- 
tion. The following program, for example, will failin line 30 witha NEXT 
WITHOUT FOR error: 








10 FOR ~ = i TO 10 —try to loop 10 times 
20 PRINT & 
30 CLEAR —CLEAR resets control stack 
(among other things) 
40 NEAT # —program fails here—doesnt 
know it’s in a loop 
20 PRINT "HIE" —program won't get this far 
The 1ST Command 
Lio 
LIST 100 
LIST 100, 
LIST - 200 
LIST +200 
LIST 100% 200 
LIST 100 - 200 


The L. IST command displays on the screen all or part of the pro- 


gram currently in memory, or writes it to the current output device as 
specified in the last Pl¥# statement. (For example, if there is a printer 
connected to slot 1, and ifthe statement Pk# 1 has been executed, 


then the program listing is sent to the printer.) 


To list the entire program, just type the keyword L. I ST and press 
: 


Lisl 


You can list a portion of the program by specifying the first and last 
lines you want to list, separated by either acomma or a dash: 


Ldat 100, 


LIST 100 


> 
Zo 


ee 
ne 


‘¢ 


2a 


General Information 


} 


—display lines 100 through 
aes 


—also display lines 100 
through 230 





_ IST indeferred execution 


If none of the lines in the specified range are in memory, nothing will 
be listed; if the specified range is greater than the actual range of 
lines in the program, Applesoft will list the entire program. 


If you specify only one line number preceded by a comma or dash, all 
lines from the beginning of the program through the specified line will 
be listed: 


LIST +100 —display from beginning of pro- 
gram through line 100 


If you specify only one line number followed by a comma or dash, all 
lines from the specified line through the end of the program will be 
listed: 


LIST i100 - —display from line 1 20 through 
end of program 


If you just specify a single line number, only that line will be listed: 
LIST 100 —display line 1&0 only 


You cannot list line number © by itself. You'll have to use a form like 


Fist 71 





Warning 


Always be sure to type the keyword L. I ST before the number of the pro- 
gram line you want to list; typing a line number not preceded by a key- 
word deletes the specified line from the program (See Section 1.1.5, 
“Deleting Lines from a Program: The DEL. Command”). 





Although the L. [ST command is usually used in immediate execu- 
tion, you can also use it from within a program: 


Lou LISt —list entire program 


200 IF 2 = K THEN LISTL 104/09 
—list lines 1 through 7 3 if vari- 
able 2 holds same value as 
variable # 


_.I ST statements within a program can be particularly useful in debug- 
ging. With them, you can test for various error conditions and display or 
print only the section of the program in which the error occurred. 


Operations On Whole Programs 








UN executes a program 


fy UN in deferred execution 


variables: see Section 2.1 


Running a program from a disk 





The RUN Command 


RUN 
RUN 273 
RUN MONTHLY BUDGET 


The RUN command instructs Applesoft to execute the program 
currently in memory. If no line number is given, execution begins at 
the beginning of the program; if the kk UN command includes a line 
number, execution begins at the specified line: 


RUN —execute program from 
beginning 
RUN 300 —execute program from line 


BOO 


If you attempt to run a program from a specified line number (as in RUN 
~ 0) and that line doesn’t exist, the message 


PUNDEF ‘D STATEMENT ERROR 


will be displayed and program execution will halt. 


Although fk UN is normally used in immediate execution, you can also 
use it from within a program: 


130 IF A = 0 THEN RUN 
—if value of A is ©, then execute 
program from beginning 
ego RUN GOO —execute program from line 


600 


You can use this technique, for example, to restart a game or to avoid 
executing some code with low line numbers. 


Warning 


Whenever the kk UN statement is executed, it resets the values of all nu- 
meric variables to © and those of all string variables to the null string be- 
fore executing the first program line. If you have assigned values to any 
variables in immediate execution, those values will be forgotten. This 
happens even if there is no program currently in memory. 


lf your computer is equipped with a disk drive and the Disk Operating 
System (DOS) is active, you can use the Rk LIN command to load a 
program into memory from a disk file and execute it. To do this, follow 
the keyword Fk UN with the file name under which the program is 


General Information 





1.2.5 


SAVE writes a program to a disk or 
tape 


Saving programs on tape: see Appen- 
dix M 


CONTROL |-|RESET| : see Section 1.3.2 


stored on the disk. For example, if the program you want to run is 
stored in a file named AWA‘, first make sure the disk containing that 
file is in the disk drive, then type 


RUN AWAY 


and press [ RETURN |. Applesoft (and DOS) will do the rest. 


If you try to use this form of the k UN command with no disk drive con- 
nected to your computer, or without DOS loaded and active, you'll get a 
syntax error. 


For more information on disk drives, disks, files, and file names, see 
the DOS manual that came with your disk drive. For related Applesoft 
commands, see Sections 1.2.5, “The SAVE Command,” and 1.2.6, 
“The L GAD Command.” For information on using a cassette tape re- 
corder in place of a disk drive, see Appendix M, “If You Have a Cassette 
Recorder.” 





The SAVE Command 


SAVE 
SAVE MONTHLY BUDGET 


On systems equipped with a disk drive, the SAE command writes 
the Applesoft program currently in memory to a file on a disk. The 
keyword SAVE is followed by the file name under which the program 
is to be written. The copy of the program in memory is not affected in 
any way. For example, 


SAVE MY CHILD —store current program on disk 
under filename Mf’ CHILD 


Attempting to use this form of the S5A'4E command with no disk drive 
connected to your computer, or without the Disk Operating System 
(DOS) loaded and active, will result in a syntax error. 


If you issue the SAVE command without specifying a file name, Apple- 
soft will attempt to write the program in memory onto a tape cassette. If 
no cassette recorder is connected, the computer will seem to hang for a 
while; the actual time that will pass before you regain control depends on 
the length of the program in memory. You can regain control immediately 


by pressing [ ConTRoL J- 


Operations On Whole Programs 





1.2.6 


LOAD reads a program from a disk 
or tape 


l¥ LIN command: see Section 1.2.4 


Loading programs from tape: see 
Appendix M 


CONTROL |-| RESET |: see Section 1.3.2 








For more information on disk drives, disks, files, and file names, see 
the DOS manual that came with your disk drive. For related Applesoft 
commands, see Sections 1.2.4, “The RUN Command,” and 1.2.6, “The 
LOAD Command.” For information on using a cassette tape recorder in 
place of a disk drive, see Appendix M, “If You Have a Cassette 
Recorder.” 





The LOAD Command 


LOAD 
LOAD MONTHLY BUDGET 


On systems equipped with a disk drive, the L OAD command reads 
an Applesoft program from a file on a disk into the computer's mem- 
ory for execution or editing. The keyword L. OAD is followed by the file 
name under which the program is to be found on the disk. For 
example, 


LOAD THE DICE —load program into memory 
from filenamed THE DICE 


|. GAD does not execute the program it retrieves; it merely reads a 
copy of the program into memory. You can then execute the program, 
if you wish, with the kk} LIN command. The copy of the program on the 
disk is not affected in any way. 


If the disk in the disk drive doesn’t contain a file of the specified name, 
the error message 


PILE NOT FUGND 


will be displayed. If there is no disk drive connected to your computer, or 
if the Disk Operating System (DOS) isn’t loaded and active, you'll get a 
syntax error. 


If you issue the LOAD command without specifying a file name, Aople- 
soft will attempt to read a program into memory from a tape casseite. If 
no cassette recorder is connected, or if the tape in the recorder doesn’t 
contain a program to load, or if the recorder is turned off, the computer 
will hang forever looking for a program that isn’t there. When you get 


bored waiting, press { conTROL |-| RESET ]to regain control. 


General Information 





1.3 


1.3.1 


CONTROL |-S temporarily suspends 


screen output 


[ CONTROL |-C: see Section 1.3.2 


1.3.2 


For more information on disk drives, disks, files, and file names, see the 
DOS manual that came with your disk drive. For related Applesoft com- 
mands, see Sections 1.2.4, “The & UN Command,” and 1.2.5, “The 

3 AVE Command.” For information on using a cassette tape recorder in 
place of a disk drive, see Appendix M, “If You Have a Cassette 
Recorder.” 


Interrupting and Resuming a Program 


Ifa program starts to run away from you, there are various ways of 
interrupting it and regaining control. This section covers Applesoft’s 
facilities for getting out of problem programming situations, infinite 
loops, and the like. 





Suspending Screen Output 


Quite often the output a program displays, or the listing of the pro- 
gram itself, exceeds the number of lines available on the display 
screen, causing the output to fly by on the screen too fast for you to 
read. In such cases, you can press [ CONTROL |-5 (type the letter 5 
while holding down the key) to suspend the output of text 
to the screen temporarily so that you can comfortably read what’s 
there. -5 doesn’t permanently discontinue the display of 
text; pressing any key, including another { ConTROL |-S, causes 
screen output to resume. You can then suspend it again with another 
-§. To discontinue a program or a listing permanently, use 
[conTROL J-C. 


Helpful Hint: Experienced programmers looking at listings of long pro- 
grams keep the key continually pressed; they control the list- 


ing by pressing the S key whenever they want to suspend or continue it. 





Interrupting Program Execution 


Applesoft gives you two ways of interrupting the execution of a run- 


ning program or canceling a listing. Pressing -C interrupts 
the program in such a way that it is usually possible to resume execu- 


tion from the point of the interruption; {CONTROL J-[ RESET] is some- 


what more drastic, and often leaves the system in a state from which 
the program can't be resumed with a CONT statement. 


Interrupting and Resuming a Program 





CONTROL |-C cancels execution or 


listing of a program 


INPUT statement: see Section 5.1.2 


GET statement: see Section 5.1.3 


ASCII code: see Section 4.2.1 and 
Appendix C 


CONTROL |-| RESET | unconditionally 


stops any program or command 


Apple Ile Monitor program: see Apple 
lle Reference Manual 








CONTROL |-C 





Pressing [ CONTROL |-C (typing the letter C while holding down the 


key) cancels the execution or listing of a program and re- 
turns Applesoft to its command level, displaying the prompt character 


(1). You can then resume execution of the program, if you wish, with 
the CONT command. To cancel execution of a program that is wait- 
ing fora response to an INPUT statement, { CONTROL |-C must be 
the first character typed and must be followed immediately by 


| 


Interrupting a GET: -C will not interrupt a program waiting 
foraresponse toa GET statement; unlike the INPUT statement, GET 


will assume that [ controt |-C is a valid response and will assign the 
ASCII code for the character [ controt |-C to the specified variable. 
To allow a program halted at a GE T statement to be interrupted with 


-C, use this form: 


220 GET AS —wait for user to press a key 


2600 iF AS = CHRS(3) [HEN SIOP 


—if user presses [ conTRot J|-C 
(ASCII code 3), then stop 





Warning 


In certain situations, using [contrat |-C can disconnect the disk operat- 
ing system. See the DOS manual for information on this point. 


[ CONTROL |-[RESET | 


In most cases you can immediately and unconditionally stop the 
execution of any Applesoft program or command by pressing 

-[ RESET | (pressing the key while holding down 
the [ CONTROL | key). The program in memory remains intact, but 
some of Applesoft’s internal “nousekeeping” information is changed; 
as aresult, it may not be possible to resume execution of the program 
with the CONT command. 





Controlling - : Your Apple Ile has an advanced soft- 


ware feature called a reset vector, which allows you to control what hap- 
pens when - is pressed. You can use the reset vector 
to make the program continue as if nothing had happened, branch to 
some other portion of the program, or do whatever you choose. Use of 
this technique requires knowledge of the Apple Ile’s built-in Monitor pro- 
gram: see the Apple Ile Reference Manual for details. 


General Information 





1.3.3 


CONT continues execution after an 
interruption 


STOP statement: see Section 3.6.1 


END statement: see Section 3.6.2 


[ CONTROL J-C: see Section 1.3.2 


When CONT won’t work 


INPUT statement: see Section 5.1.2 


Tutorials abound... 


1.4 


Resuming Program Execution: 
The CONT Command 


CONT 


The CONT (for “continue”) command is used to resume execution cf 
a program after it has been interrupted bya STOP or END statement 
or by pressing -C. Execution will continue at the first state- 
ment after the 5 TOP or END, or atthe point in the program where 


execution was interrupted by -C. 


CONT won't work if 


@ the program has been stopped because of an error 
® anerror has occurred in immediate execution 
@ anINPUT statement has been interrupted with ( conTRot |-C 


® any program line has been edited since the program stopped 
running 


However, you can continue the program with CONT after examining 
or changing the values of variables, provided you haven't edited any 
program lines. 


When a program is interrupted with -[ RESET |, CONT mayor 


may not be able to continue execution. Let the programmer beware! 


Warning 


The CONT command should be used in immediate execution only. If itis 
executed from within a program, it will cause the program to hang. 


Editing What You Type 


This section gives a very brief description of Applesoft’s facilities for 
correcting typing mistakes and editing text on the screen. More de- 
tailed discussions of these features can be found in the Apple Ile 
Owner’s Manual and the Apple Ile App/esoft Tutorial. For hands-on 
experience with the various keys and editing features, use the 
APPLE PRESENTS... APPLE training disk. 


Editing What You Type 








1.4.1 


CONTROL |-X cancels a line of input 


1.4.2 


pure cursor moves: see Section 1.4.3 





Canceling an Input Line 





[ CONTROL |-X is your “escape hatch.” By typing the letter * while 
holding down the [ control} key, you can change your mind (as long 
as you haven’t yet pressed the key) and cancel a program 
line that you’re entering or editing or a line of input that you're in the 
midst of typing to a program. Applesoft will display a backslash (\) at 
the end of the line you were typing, to show that it’s ignoring that in- 
put, and will redisplay the cursor at the beginning of the next line of 
the screen. 











@ Ifyou were typing a new program line, the whole line is elimi- 
nated and you can start over again. 


@ Ifyou were retyping a previously entered program line, any 
changes you had typed will be canceled. 


@ Ifyou were typing input to a running program, the line you were 
typing is ignored and the program waits for your new response. 


-% does not affect any previous input you've typed or pro- 
gram lines already entered. 





The Arrow Keys 


There are four arrow keys on the Apple Ile keyboard: 


@ The key works as a backspace. It moves the cur- 


sor one position to the left and “erases” the last character typed 
from the keyboard (or recopied with the | RIGHT-aRRoW | key; see 
below). No characters are removed from the screen, but the last 
character typed is forgotten, as if it had never been typed. 


@ The| RIGHT-ARROW | key “recopies’ the character under the cur- 


sor as if it had been typed from the keyboard, then moves the 
cursor one position to the right. Moving the cursor over a charac- 


ter with{ RIGHT-ARROW jis exactly the same as typing that char- 


acter from the keyboard. 





@ The [ DOWN-ARROW| moves the cursor down one line without eras- 
ing or recopying any characters. 


@ The key has no effect in Applesoft. 


Notice that the | LEFT-arRow| key doesn’t erase any characters from the 
screen, it just tells Applesoft to “forget” the last character it received. If 
any pure cursor moves have been used, the character “erased” may not 
even be the one the cursor backs up over. 





General Information 





escape mode: see Section 1.4.3 


INPUT statement: see Section 5.1.2 
GET statement: see Section 5.1.3 


ASCII: see Section 4.2.1 and Appendix C 


Table 1-1 ASCII Equivalents of Arrow 
Keys 


ASCII Keyboard 
Key Code Equivalent 


21 CeonTRou|-u 
11 (GonTROL |-K 
10 (CONTROL |-s 


1.4.3 


alters meanings of some keys 


In escape mode, all four arrow keys function as pure cursor moves, 
equivalent to I (up), J (left), K (right), and M (down). Thatis, they 
lose their backspace and recopy functions and simply move the cur- 
sor one position in the indicated direction, remaining in escape 
mode. To cancel escape mode after moving the cursor, press the 


bar. 


The Apple Ile keyboard’s auto-repeat feature is particularly handy for 
long cursor moves. If you press and hold down any of the arrow keys, the 
cursor will move repeatedly in the indicated direction for as long as you 
hold down the key. (Exception: the key doesn’t move the 
cursor unless you’re in escape mode.) 


For Experts Only: The and keys can be 


typed by the user in response to an INPUT statement ina running Ap- 
plesoft program. ([LEFT-arrow | and can’t be, because 
they’re interpreted as backspace and recopy, even in program input; but 
any of the four arrow keys can be typed as aresponse toa GET state- 
ment.) In your own programs, you can make the arrow keys mean just 
what you choose them to mean (neither more nor less) by having the 
program test the input for each arrow’s ASCII value, as shown in Table 1- 
1. The program can then take any action you want on receiving one of 
these codes from the user. 


(“The question is,” said Alice, “whether you can make keys mean so 
many different things.” 


“The question is,” said Humpty Dumpty, “which is to be master—that’s 
all.”) 





Escape Mode 


Pressing the (for “escape’) key puts Applesoft into a state 
called escape mode, in which certain keys take on special mean- 
ings. Some of the keys become pure cursor moves, meaning that 
they move the cursor around on the screen without erasing or 
recopying characters or affecting Applesoft’s input in any way. Others 
can be used to clear away all text from all or part of the screen, again 
without having any effect on the input received by Applesoft. 


Although Applesoft normally doesn’t understand lowercase letters, it will 
accept them in escape mode. All of the letter keys listed below will have 
the same effect whether they are typed in upper- or lowercase. 


Editing What You Type 





Figure 1-1 Single Cursor Moves 


A, 6, C, D move cursor one position 


Figure 1-2 Long-range Cursor Moves 


I, J, K, M are for long-range moves 


Arrows also work for long-range moves 


E, F, @ clear all or part of the screen 


text window: see Section 5.2.4 








In escape mode, the following characters move the cursor one posi- 
tion in the stated direction and then leave escape mode. To continue 
moving the cursor, you have to press the key again. The func- 
tions of these keys are illustrated in Figure 1-1. 


@ A moves the cursor one position to the right. 

@ 6B moves the cursor one position to the left. 

@ moves the cursor down one line. 

@ D moves the cursor up one line. 

The following characters move the cursor one position in the stated 
direction and remain in escape mode. You can then continue moving 
the cursor without pressing the key again. These keys are 
especially useful for long-range cursor moves. The functions of these 
keys are illustrated in Figure 1-2. 

@ I moves the cursor up one line. 

@ .jmoves the cursor one position to the left. 

@ K& moves the cursor one position to the right. 


@ fii moves the cursor down one line. 


Notice that the I, J, K, and M keys form a diamond shape on the key- 
board, representing the directions in which these keys move the cursor 
(I up, J left, K right, M down). 


The four arrow keys function in escape mode exactly the same as !, WJ, 
kK , and M. That is, they move the cursor one position in the indicated di- 
rection and remain in escape mode. 


The Apple Ile keyboard’s auto-repeat feature is particularly handy for 
long cursor moves. If you press and hold down I, J, K, M, or any of the 
arrow keys while in escape mode, the cursor will move repeatedly in the 
indicated direction for as long as you hold down the key. 


In escape mode, the following keys clear away all text from all or part 
of the display screen and then leave escape mode: 
@ clears from the current cursor position to the end of the line. 


@ F clears from the current cursor position to the end of the text 
window. 


@ clears the entire text window and moves the cursor to the top- 
left corner. 


General Information 





The special functions of all keys in escape mode are summarized in 
Table 1-2. To leave escape mode, press any key except one of those 
listed in the table. 


Leaving escape mode To avoid inadvertently pressing a key that has a special meaning, it’s 
safest always to use the bar to leave escape mode. 


Table 1-2 Escape-Mode Functions 
Key 


LEFT-ARROW 
RIGHT-ARROW 


UP-ARROW 


DOWN-ARROW 


Editing What You Type 


Function 


Moves cursor right one position; leaves escape mode 
Moves cursor left one position; leaves escape mode 
Moves cursor down one line; leaves escape mode 


Moves cursor up one line; leaves escape mode 


Moves cursor up one line; remains in escape mode 
Moves cursor left one position; remains in escape mode 
Moves cursor right one position; remains in escape mode 


Moves cursor down one line; remains in escape mode 


Moves cursor left one position; remains in escape mode 
Moves cursor right one position; remains in escape mode 
Moves cursor up one line; remains in escape mode 


Moves cursor down one line; remains in escape mode 


Clears from cursor to end of line; leaves escape mode 
Clears from cursor to end of text window; leaves escape mode 


Clears entire text window; moves cursor to top-left corner; leaves 
escape mode 








General Information 
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variables: see Section 2.1 


assignment statement: see Section 2.2 


expressions, precedence rules: see 
Section 2.3 


functions: see Section 2.4 


2.1 


variable: a symbol representing a loca- 
tion in the computer's memory where a 
value can be stored 


Variable types 


real variables: see Section 2.1.2 


Variables and Arithmetic 


This chapter deals with variables and arithmetic in Applesoft. These 
concepts are fundamental to Applesoft programming and will appear 
again and again throughout this manual. 


Section 2.1, “Variables,” discusses how to define and use variables, 
the various types of variable available in Applesoft, and the rules for 
naming them. 


Section 2.2, “Assigning Values to Variables: The Assignment State- 
ment,” deals with one of Applesoft’s most basic types of statement, 
the assignment statement. 


Section 2.3, “Expressions,” discusses arithmetic operators and 
expressions and the rules of precedence that govern them. 


Section 2.4, “Functions,” covers Applesoft’s built-in arithmetic func- 
tions and tells how you can define your own functions. 


Variables 


A variable is asymbol representing a location in the computer's 
memory where a value can be stored. The first time your program as- 
signs a value to a particular variable, Applesoft automatically allo- 
cates a memory location or locations for that variable and stores the 
specified value at that location. Thereafter, whenever your program 
uses that particular variable name, Applesoft will take the name to 
refer to the value stored at the corresponding location. For instance, 
if the variable P I refers to amemory location where the value 
3+14159 is stored, thenthe statement PRINT PTI willdisplay 
the value 3.14139 onthe screen. 


Applesoft has three types of variable: 


@ Real variables can contain either whole numbers or numbers 
containing decimal fractions. 
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integer variables: see Section 2.1.3 


string variables: see Section 2.1.4 


arrays: see Section 2.1.5 


Reals save time; integers save space 


subroutines: see Section 3.4 


loops: see Section 3.3 


Rules for variable names 


Table 2-1 Variable Types 








@ Integer variables can contain whole numbers only. 


@ String variables can contain strings of text characters such as 
words or names. 


In addition, Applesoft allows you to define collections of variables, 
called arrays, of any of the types listed above. 


Programming Tip: Applesoft converts all integer values to real form be- 
fore performing arithmetic on them. Because this conversion takes time, 
integer arithmetic is considerably slower than arithmetic on real quan- 
tities. However, integers take up less space in the computer's memory 
than real numbers. In relatively small programs in which space is not a 
concern, you Can speed up your program by using real variables instead 
of integers wherever possible, especially in subroutines, loops, and 
other sections of code that are executed many times. In large programs 
where space is critical, you can save space at the expense of time by 
using integers instead of reals, particularly in arrays containing many 
elements. See Appendix G, “Hints for Program Efficiency,” for further 
suggestions on how to save space and time in your programs. 





Variable Names 


The name of a variable must begin with a letter of the alphabet, which 
may be followed by one or more letters and/or digits. In addition, the 
names of all integer variables must end with a percent character (4) 
and those of string variables must end with a dollar sign (#). The var- 
ious variable types and the rules for naming them are summarized in 
Table 2-1. 


Simple Array 
Type Symbol Examples Examples 
Real (none) K AGE (CHILD) 
PRICE TAX CITEM) 
Ni Ni the 3? 
Integer A toh de YEARZ (N) 
GOA BOOKZ (COUNT) 
Nix NLA id4¢e 3) 
String $ At SHOPS (3) 
SAMS DAY (WEEK) 
Nig Nit (J4+ 3) 
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Don’t begin variable names of the same 
type with the same first two characters 


Reserved words illegal in variable 
names 


Range of real values 


Real variable names consist of letters 


and digits only 


Real variables preset to © 


A variable name can be up to 239 characters long, but Applesoft uses 
only the first two characters to distinguish one variable from another 
of the same type. All characters beyond the first two in a name are Ig- 
nored, so long as they don't include a reserved word (see below). 


Take care not to begin the names of different variables of the same type 
with the same two characters. Applesoft will consider the names SUM 
and SUNS TROKE, for example, to refer to the same variable, since 
they both begin with the same two characters. 


Notice that the restriction above applies only to variables of the same 
type. Thenames TAX, TAA4%,and TAA referto three different 
variables, even though they all begin with the same two characters, be- 
cause they are of different types (real, integer, and string). However, 
names of the same type that begin with the same two characters—such 
as (Ax and TAAAGLE, 1HI&A and [HIN«A or CIIERS 
and OTHER %—refer to the same variable. 


Reserved Words: Certain words used in Applesoft are reserved for 
special uses in specific commands; you can’t use these words as vari- 
able names or as parts of variable names (even beyond the first two 
characters). Forinstance, TOTAL or SUBTOTAL would be illegal as 
variable names, because they both contain the reserved word T 0. See 
Appendix D, “Reserved Words,’ for a list of Applesoft’s reserved words. 





Real Variables 


A real variable can hold any numeric value, with or without a 
decimal point, between -9.9SS9S9S9S99SE+ 37 and 
+9,99999999E+ 37 (where “E+ 37” means ‘times 10 
to the + 37th power’). Applesoft represents real numbers to 
32 bits (about 9 digits) of precision. 


The name of a real variable must consist of letters and digits only. 
Some legal real variable names are 


SAM 

TAA 

Q 7 
SUMOFALLNUMBERS 


Until they are given some other value with an assignment statement, 
all real variables are preset to the value ©. 





Integer Variables 


Integer variables can hold only whole-number values between 
— 32767 and + 3276/7. The name ofan integer variable must 
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Integer variable names end with % 


Integer variables preset to © 


Real values assigned to integer variables 
are truncated, not rounded 


2.1.4 


string: a sequence of text characters; 
see Section 4.2 


String constants enclosed in double 
quotation marks 


null string: a string containing no 
characters 








end with the percent character (4). Some legal integer variable names 
are 


SHARE’ 
D3% 
TAA 


Until they are given some other value with an assignment statement, 
all integer variables are preset to the value ©. 


lf a number containing a decimal fraction is assigned as the value of 
an integer variable, it is truncated to the next lowest whole number— 
not rounded to the nearest whole number: 





LET AZ = 32.678 —value 32 assigned to variable 
A‘ 

LET BA = —-34.2 —value — 35 assigned to vari- 
able Bz, 

String Variables 


A string is a sequence of text characters (letters, digits, and punctua- 
tion marks). Just as you can write numeric constants such as 2? and 
< + <6 in your Applesoft programs, you can write string constants 
by enclosing the characters in the desired string between double 
quotation marks: 


"NOT WITH A BANG BUT A WHIMPER" 
"George Bernard Shaw" 

"H2E34I7" 

MEP RL EZ" 


Even though Applesoft doesn’t understand lowercase letters when you 
use them in keywords, it will allow you to use them in a string constant, 
as the second example above shows. 


A string can contain from 0 to 255 characters; when it contains no 
characters it is called a null string. Two quotation marks with nothing 
between them denote the null string: 


—a string with no characters 
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String variable names end with # 


String variables preset to null string 


array: a collection of variables referred to 
by the same name and distinguished by 
means of numeric subscripts 


simple variable: a variable that is not an 


element of an array 


Figure 2-1 A Typical Array 


Fy 


FR 


FR 


fy 


RR 


Array 





A string variable can hold any string as its value. Its name must end 
with a dollar sign (#). Some legal string variable names are 


NAME $ 
So 4 
Jj 


Until they are given some other value with an assignment statement, 
all string variables are preset to the null string. 





Arrays: Collections of Variables 


An array is acollection of variables referred to by the same name, 
usually holding a collection of data items that are related to each 
other in some logical or systematic way. The individual variables in 
the array are called its elements, and are distinguished from one an- 
other by means of identifying index numbers called subscripts. 


An array can be of any type: integer, real, or string. Array names fol- 
low the same rules as simple variable names of the same type. To re- 
fer to a particular element of an array, write the array name followed 
by one or more subscripts, separated by commas and enclosed in 
parentheses. The subscripts refer to the position of the desired ele- 
ment within the array: 


O (6) —element & of real array 9 

FIGURE” (N) —element N of integer array 
FIGURE? 

NAMES (J - 3) —element J - 3 ofstring ar- 
ray NAMES 

COUNT (SUMZ+ 2) —element (SUMZ+ 2) ofreal 
array COUNT 


Figure 2-1 shows a real array named fF with five elements, numbered 
Oto 4. Element F ¢ @ ) (pronounced “R-sub-zero”) holds the value 
23,R¢1) holds 27.33, andsoon. Ifthe value of variable 5 is 2, 
then the expression Fk (5) refers to element IX ( 2} , whose value is 
31.4,andtheexpressionk(S + 2) referstoelementk (4), 
which holds the value i 9. 


For a fuller discussion of arrays and their use, see Section 4.1, 
“Arrays.” 
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es «Assigning Values to Variables: The 
*2 Assignment Statement 


Let Fi 
COUNTS? 


Je Lolsodzbso 
0 


Before Applesoft begins executing a program, it sets the values of all 
Assignment statement assignsanew real and integer variables to @ and the values of all string variables to 
value to a variable the null string (that is, a string containing no characters). The pro- 
gram can then change the value of any variable at any time by exe- 
cuting an assignment statement. 


The NEW, CLEAR, and RUN commands also reset all real and integer 
variables to ® and all string variables to the null string. 


An assignment statement consists of the optional keyword LET, fol- 
lowed by the name of the variable whose value is to be changed, an 
equal sign (=), and an expression denoting the new value to be as- 
signed to that variable. The equal sign means “receives the value” or 
“is assigned the value”; it is often read simply as “gets” (“4 gets ¥ 
plus =”). The assignment statement means “evaluate the expression 
NEW command: see Section 1.2.1 to the right of the equal sign and assign the resulting value to the vari- 
able named to the left of the equal sign.” The variable will then con- 


CLEAR command: see Section 1.2.2 ita 
tinue to hold that value until it is changed by another assignment 


FX UN command: see Section 1.2.4 statement or is reset bya NEW, CLEAR, or RUN command. For 
example, 
Keyword LE T is optional LET 9 = 27,4 —assign value = 7.4 toreal 
variable & 
LET D3 = J —assign current value of real 


variable .J to real variable D3: 
variable .j unchanged 


COUNTAZA = A + B —assign current value of real 
variable A plus current value 
of real variable B to integer 
variable COUNT %; variables A 
and B unchanged 


S594 = 33 —assign value 33 to integer 
variable 594 

NAMES = "SAM" —assign string value "SAM" to 
string variable NAME % 
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2.3 


arithmetic operators: see Section 2.3.1 


relational operators: see Section 2.3.2 


logical operators: see Section 2.3.3 


2.3.1 


Arithmetic operators combine nu- 
meric values to produce numeric 
results 


NAMES = SAMS —assign current value of string 
variable SAM $ to string vari- 
able NAME $; variable SAM 
unchanged 


BOACS) = 36 —assign value 36 to element 3 
of real array BOA 


Jhé = AACN) —assign current value of ele- 
ment N of integer array 4%. to in- 
teger variable J4; array A% and 
variable N unchanged 


SHOP$(N) = "BAKERY" —assignvalue "BAKERY" to 
element N of string array 
SHOP $ 


The keyword L.E T is optional in assignment statements. The statements 
LET 9 = 27.4 

and 

QO = 27.4 


mean exactly the same thing. 


Expressions 


An expression is a formula describing a calculation for the computer 
to perform. It may involve any number of numeric variables and con- 
stants, together with operators specifying how the values of the vari- 
ables and constants are to be combined. There are three kinds of 
operator that can be used in an Applesoft expression: 


e@ Arithmetic operators combine two numeric values and produce a 
numeric result. 


@ Relational operators compare two values and produce a logical 
(true-or-false) result. 


@ Logical operators combine two logical values and produce a logi- 
cal result. 


Table 2-2 summarizes the various operators available in Applesoft. 





Arithmetic Operators 


Arithmetic operators combine two numeric values to produce a nu- 
meric result. There are five of them in Applesoft, corresponding to the 


Expressions 





Table 2-2 Operators 


Arithmetic Operators 


+ addition 

= subtraction 

% multiplication 
/ division 


exponentiation 


Relational Operators 


equal to 

less than 

greater than 

less than or equal to 


AVA Il 


VA | 
AVV IAI 


greater than or equal to 


not equal to 


Logical Operators 
AND both true 


OR either or both true 
NOT is false 





familiar operations of arithmetic: + (addition), — (subtraction), * 
(multiplication), / (division), and ~ (exponentiation). Here are some 
examples of their use: 


34+ 4 
+144 
x + Y 


gaef = Lied 


oy =~ so 


—144 


Saha — 2 

lj #2 3 

oS € sam 

eo * QUARTERSZ 


4,8 * COUNT(S) 


i8 / 6 
S / is 


DIST / TIME 


DOLLARS’ / 100 


o * 3 
3° 45 
oe a9 


—3 plus 4, yielding 7 
—plus 1 44 (a positive number) 


—the value of # plus the value 
of * 


—£3+/minus 11. 4, yielding 
2+ 


—30 minus 73, yielding — 23 


—minus 1 44 (anegative 
number) 


—the value of SUM minus 2 


—is3times 3, yielding 635 


ay 


—6 times + £3, yielding i. 


—<5 times the value of 
QUARTERS? 


—4.8 times the value of ele- 
ment 3 of array COUNT 


— 18 divided by &, yielding 3 


—6 divided by 18, yielding 
(SIGs sIGd 


—the value of DI ST divided by 
the value of TIME 


—the value of DOLLARSZ 
divided by 100 


—< tothe 3rd power, yielding 8 


—‘3 tothe + 3 power, yielding 
1,73203081 


—the value of % raised to the 
power of the value of J % 


Like most other computer languages, Applesoft uses an asterisk (*) in- 
stead of the letter % to represent multiplication. 
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2.3.2 


Relational operators compare values 
and produce logical results 


1 stands for true 


© stands for fa/se 


What to Do with Fractions: Applesoft doesn’t treat fractional numbers 
in the way that you are probably used to dealing with them. Most people 
would read the expression 3 3/4 as “three and three quarters.” To 
Applesoft, however, the same expression would mean “thirty-three di- 
vided by four.” (Applesoft ignores any spaces it finds in a number.) 


It’s easy to convert fractions to a form Applesoft will understand cor- 
rectly. Just think of 3 3/4 as “three plus three divided by four”. In 
other words, instead of typing 

LET A = 3 374 

type this instead: 

Lei A = 3 + S/G 


Applesoft will do the rest. 





Relational Operators 


A relational operator tests for a relation between two values and pro- 
duces a logical (true-or-false) result, depending on whether the par- 
ticular relation does or doesn’t hold between those two values. For 
example, the expression 


A > B 


means “the value of variable A is greater than that of variable B.” If 
the current value of variable 4 is 3 and that of B is 3, then the relation 
is true; if the value of B is &, the relation is false. 


Relational operators are particularly useful in connection with the 
IF... THEN statement, discussed in Section 3.2.2. 


The Truth about Applesoft: Applesoft actually uses numeric values to 
represent the logical values true and false: if the stated relation is true, 
the value of the relational expression is 1; if the relation is false, the 
value of the expression is ®. For example, if you type the statement 
PRINT G@ > 12 


in immediate execution, Applesoft will respond by displaying the number 
©, meaning ‘false’; if you type 


PRINT i2 > 6 


Applesoft will display the number i, meaning “true.” 
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= means equal to 


= means /ess than 


* means greater than 

* = or = * means/ess than or equal to 
* = Or = » means greater than or 
equal to 


Applesoft has six relational operators (some of which can be written 
in more than one way): = (equal to), < (less than), > (greater than), 
<= or =< (less than or equal to), > = or = > (greater than or 
equal to), and <> or >< (not equal to). Here are some examples of 
their use: 


Vf a) 
i’ ra 


NAMES = “Ann” 


PROBABILITY < 4.3 


* Ba 
* Bu 


GHlW Gin bb hh] Go 
> 
V 
| /\ 
| 
feceeke 
fr 


=> 12 


SALARY >= 20000 
SALARY => 20000 


Variables and Arithmetic 


—6 equals 6, yielding 1 for true 


—6 equals i =, yielding ® for 
false 


—the value of * is equal to = 


—the value of NAME $ is equal 
to the string "Ann" 


—6 is less than &, yielding © for 
false 


—6 isless than 1 2, yielding i 
for true 


—the valueof PROBABILITY 
isless than «3 


—6 is greater than &, yielding © 
for false 


—6 is greater than i =, yielding 
© for false 


—the value of AGE is greater 
than 6&3 


—6 is less than or equal to &, 
yielding i for true 


—6 is less than or equalto i 2, 
yielding i for true 


—the value of 4% is less than or 
equal to 3 times the value of B%. 


—6 is greater than or equal to &, 
yielding i for true 


—6 is greater than or equal to 
=, yielding © for false 


—-the value of SALARY’ is 
greater than or equal to 


LOOO0 


‘oe! ‘ee ee ' 





. - or +4 means not equal to 


2.3.3 


Logical operators combine logical val- 
ues to produce logical results 


AND yields true if both original expres- 
sions are true 


OR yields true if either or both of the 
Original expressions are true 


NOT yields true if the original expression 
is false 





Ss <> §& —G is not equal to &, yielding © 

G >< G for false 

G6 <> 12 —6 is not equal to i =, yielding 

G >< 12 1 for true 

X <> ¥ —the value of # is not equal to 

x >< ¥ the value of */ 

BANGS >< "WHIMPER" —the value of BANG $ is 

BANGS <> "WHIMPER" not equal to the string 
“WHIMPER ® 

Logical Operators 


A logical operator combines two logical (true-or-false) values and 
produces a logical result. There are three logical operators in Apple- 
soft: AND, OR, and NOT. Here are some examples of their use: 


G <= if AND 6 >= Ilé 
—G is less than or equalto iz 
and & is greater than or equal 


to i=; value is © for false 
~25 <= FR AND R < .75 


—,2£3 is less than or equal to 
the value of f* and the value of 


Fislessthan. 73 
G <= 12 0R 6 >= 12 | 
—b6 is less than or equal to iz 
or G is greater than or equal to 


~ value is 1 fortrue 


ANIMALS = "DOG" OR ANIMALS = "CAT" 
—the value of ANI MAL $ is 
equal to the string "DOG" or 
the string "CAT" 


NOT (6 <= 12) —6 is not less than or equal to 
=; Value is © for false 
NOT (YEARA > 19380) —the value of YEAR is not 


greater than 1930 


Notice that the OR operator doesn’t correspond exactly to the way we 
often use the word “‘or’ in everyday speech. When we say “Aor Bis 
true,” we usually mean that exactly one of the two statements is true, but 
not both. The Applesoft OR operator produces a “true” value if either or 
both of the original expressions are true. 
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© means false 


Any nonzero value means true 


Table 2-3 Precedence of Operators 





2.3.4 





More Truth about Applesoft: Applesoft’s logical operators consider a 
numerical value of & to mean “false”; any numerical value other than © 
is taken to mean “true.” The logical operators always yield a value of 1 
for true or © for false. 


Logical operators are particularly useful in connection with the 
IF... THEN statement, discussed in Section 3.2.2. 





Precedence of Operators 


Operators in Applesoft have an order of precedence that determines 
which operations are carried out first when they are combined in an 
expression. Table 2-3 lists the operators in descending order of prec- 
edence. Operators shown higher in the list are carried out before 
those lower down. Operators on the same line of the list have the 
same precedence, and are carried out from left to right within an 
expression. 


Parentheses (innermost first) () 


Signed arithmetic andlogicalNOT + — NOT 

Exponentiation (powers of 

numbers) 

Multiplication and division % # 

Addition and subtraction - = 

Relational operators = £_ - = =f Se ss > oS 
Logical AND AND 

Logical OR OR 


Notice in Table 2-3 that the operators + and — have higher precedence 
when used to represent the sign of a single number (as in + 144 or 

— 4) than when they stand for the addition or subtraction of two 
numbers. 


To understand how Applesoft’s precedence rules work, consider the 
expression 


—~2£ & £ ° 2 + Ws 3S > Re G 


When Applesoft evaluates this expression, it begins by applying the 
first minus sign to the constant =, obtaining a result of — 2. Next it 
raises the value of 2 to the 3rd power and multiplies the result by 

— =. Then it divides the value of & by 3 and adds the result to that of 
the previous calculation. Finally, it multiplies the values of A and B 
and subtracts that result from the previous one. 
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Parentheses change order of 
evaluation 


2.4 


function: a preprogrammed calculation 
that can be carried out on request 


For example, suppose the current values of the variables in the 


expression above are as follows: 2 =2,9 = 10,A = 7,B = 4. 
Then 

£ = 2°” 3 = 8 

—2¢ € & = —16 

QO / 3 = 10 ¢ 2 = 2 

—16 + 2 = —14 

A * B = 7 * 4d = 2: 

=i = 28 = —42 


The value of the expression is — 4<. 


Parentheses can be used to change the normal order of precedence. 
For example: 


=f * 2£ ” {2 + B81 # BO -—- A ® B 
—value is —3304,8: 
(3 + @) evaluatedasa 
unit 


—2f * 2 * 3 + (0 / 3 -— AD * B 
—value is — 36; 
(Q / 3S — &#) evaluated 
as aunit 


—2 * £ * 9+ 0 / (3 -—- A *® B) 
—valueis —16.4347826; 
(QO / (5 -—- A * B)) 
evaluated as a unit 


The original expression above is equivalent to the fully parenthesized 
expression 


(CC—2) / (fl " 3)) + (HY £ 3d) -— (A *® 8) 


Helpful Hint: When you're unsure of the order of precedence, use pa- 
rentheses to make sure the expression is evaluated in the order you 
intend. 


Functions 


Functions are preprogrammed calculations that can be carried out 
on request. You can use them whenever you need to perform the 
same calculation repeatedly throughout a program. Whenever you 
call a function (request its execution), you must give it a particular 
value to operate on; this value is called the argument of the function. 
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Calling built-in functions 


ABS computes the absolute value 


2.4.1 





Applesoft offers a variety of built-in functions, discussed in Section 
2.4.1, for calculating common mathematical values such as loga- 
rithms, cosines, and square roots. Section 2.4.2 covers the built-in 
function k ND, used for generating random numbers. In addition, you 
can define your own functions for the special needs of a particular 
program—see Section 2.4.3 for details. 





Built-in Arithmetic Functions 


This section discusses the various built-in functions that Applesoft 
provides for calculating commonly used mathematical quantities. To 
call a built-in function, just type the name of the function followed by 
an expression in parentheses representing the argument value on 
which you want the function to operate. For example, suppose you 
need to calculate the square root of anumber. Applesoft has a built-in 
function named 54 for this purpose; to find the square root of 33, 
write 


SOR (3) 
To find the square root of the value of variable * plus =, write 
SOR (A+2) 


The ABS Function 


The built-in function ABS computes the absolute value of anum- 
ber—that Is, the positive numerical value of the number, without re- 
gard to its original sign. For example, 


ABS (27) —absolute value of = 7; yields 
a? 

ABS (—-27) —absolute value of — = 7; yields 
a? 

ABS (3648 — 2449) —absolute value of 36.3 
minus =3+3;yields 13.35 

AOS Ced+a — 36.8) —absolute value of 23.3 
minus 36.8;yields 13.35 

ABS (C4(9)) —absolute value of element © of 
array CA 
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5GN computes the sign of a number 


INT computes the integer part ofa 
number 


integer: a whole number 


The SGN Function 


The SGN function determines whether the value of its argument is 
positive, negative, or zero. It yields a result of 1 if the argument value 
is positive (greater than ©), — i ifthe argument value is negative 
(less than ®), and © if the argument value is ©. For example, 


SGN (27) —sign of = 7; yields i (positive) 

Siam t—2s2 —signof —=/;yields — 1 
(negative) 

SGN (36.48 — 2344) —signof 36.8 minus 23.3; 
yields 1 (positive) 

SGN (2900 — 3648) —signof23.3 minus 3G. 8; 
yields — i (negative) 

SGN (2 ¢ 2 = 4a) —sign of 3 times 3 minus 43; 
yields © 

SGN (SUM — 20) —sign of SUM minus 20 


The INT Function 


INT yields the integer (whole-number) part of its argument value, 
with the fractional part (if any) discarded. Note that this function 
makes no attempt at rounding: that is, if the argument value is not an 
integer, INT yields the next lowest integer, not necessarily the near- 
est integer. For example, 


INT (27) —integer part of = 7; yields 27 

INT (36.8) —integer part of 36.8; yields 
36 

IMT 4—fae2 —integer part of — 7.4; yields 
=i 

INT 4=—-Beel; —integer part of —62.1;yields 
—G2 

INT (3 * PRICE) —integer part of 3 times 
PRIGE 


Rounding a Number: To round a numeric value to the nearest integer, 
firstadd «5 and then apply the INT function to the result. For example, 
to find the nearest integer to the current value of variable AGE, use the 
expression 


IN? (AGe 4+ 49) 
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5 Ql computes the square root 


Square root of a negative number is an 
error 


5 IN computes the sine 


Arguments to trig functions must be in 
radians, not degrees 


COS computes the cosine 


40 


The SQ Function 


The 58 function computes the positive square root of its argument. 
For example, 


SOR (169) —square rootof i639; yields 13 

SOR (163.84) —square rootofi63.84; 
yields 12.8 

SOR (3) —square root of :3; yields 
1,732035081 

SOR (X°2 4+ 9) —square root of * squared plus 
s 


If you try to take the square root of anegative number, an ILLEGAL 
QUANT ITY error will occur. 


The SIN Function 


S IN computes the trigonometric sine of its argument. The argument 
must be expressed in radians. For example, assuming the value of 
the variable Plis3.14139265, 


SIN (PI / 3) —sineofPI / radians; 
yields «866025403 

SIN (1) —sine of 1 radian; yields 
»B841470985 

S48 AR” ef — TT 22 —sine of 4 Squared minus *’ 
Squared 


The argument you supply to the 5 I N function must be expressed in ra- 
dians, not degrees. (There are 27 radians in a circle; one radian is equal 
to approximately 57.2957795 degrees.) For a formula you can use to 
convert from degrees to radians, see Section 2.4.3, “Defining Your Own 
Functions: The DEF FN Statement.” 


The COS Function 


COS computes the trigonometric cosine of its argument. The argu- 
ment must be expressed in radians. For example, assuming the 
value of the variable PIlis3,14159265, 


lilies §£ PL ¢ 32 —cosineofPI / Sradians; 
yields +3 

GCOS (13 —cosine of i radian; yields 
»LOO202Z306 
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Arguments to trig functions must be in 
radians, not degrees 


TAN computes the tangent 


Arguments to trig functions must be in 
radians, not degrees 


A TN computes the arc tangent 


Result of A T N function is in radians, not 
degrees 


wile 4A & — Fd 


—cosine of 4 squared minus *' 
squared 


The argument you supply to the CQ5 function must be expressed in ra- 
dians, not degrees. (There are 27 radians in a circle; one radian is equal 
to approximately 57.2957795 degrees.) For a formula you can use to 
convert from degrees to radians, see Section 2.4.3, “Defining Your Own 
Functions: The DEF FN Statement.” 


The TAN Function 


T AN computes the trigonometric tangent of its argument. The argu- 
ment must be expressed in radians. For example, assuming the 
value of the variable Plis3.141 339265, 


TAN (PI / 3) —tangentofPI / S3radians; 
yields i. 7320508 
TAN (1) —tangent of I radian; yields 


Lae? G07 fe 


TAN (K°S -— ¥°2) —tangent of * squared minus * 


Squared 


The argument you supply to the T AN function must be expressed in ra- 
dians, not degrees. (There are 27 radians in a circle; one radian is equal 
to approximately 57.2957795 degrees.) For a formula you can use to 
convert from degrees to radians, see Section 2.4.3, “Defining Your Own 
Functions: The DEF FN Statement.” 


The ATN Function 


& TN computes the trigonometric arc tangent (inverse tangent) of its 
argument: that is, the angle whose tangent is equal to the given 
value. The result is expressed in radians. For example, 


ATN (SQR(3)) —arc tangent of the square root 
of 3;yields i.04719735 
(= PI / 3)radians 

ATN (1) —arc tangent of 1; yields 


» 785398163 radians 


—arc tangent of « Squared 
minus *f squared 


ATN (K°S -— ¥°2) 


The result produced by the AT N function is expressed in radians, not 
degrees. (There are 2m radians in a circle; one radian is equal to approx- 
imately 57.2957795 degrees.) For a formula you can use to convert from 
radians to degrees, see Section 2.4.3, “Defining Your Own Functions: 
The DEF FN Statement.” 
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E *~P computes the exponential 


E *P accurate to six places 


LOG computes the natural logarithm 


Logarithm of a nonpositive number is an 


error 


l¥ ND generates random numbers 





2.4.2 





The EXP Function 


The EXP function computes the mathematical exponential of its ar- 
gument. The exponential is defined as the constant e raised to the 
power of the argument, where e = 2.718281828. For example, 


EARP a3) —e to the 3rd power; yields 
a¥«+UGoo0bR 

EAP (LOGC1O)) —e to the power of the natural 
logarithm of 10; yields 10 

EAP (A * T) —etothepowerA * T 


Limited Accuracy: Although Applesoft will display the result of the 
EP function to nine places, only the first six are actually reliable. For 
instance, in the first example above, the computed result of 
29,0835 369 shouldbe interpreted simply as 20.0855. 


The OG Function 


L.OG computes the natural logarithm of its argument (the logarithm to 
the base e, where e = 2.718281828.) For example, 


LOG (10) —natural logarithm of 1 &; yields 
2+ dlZo8S08 

LUG CEAPLS) 2 —natural logarithm of e to the 
3rd power; yields 3 

LOG (SIN(CTHETA)) —natural logarithm of the sine of 
THETA 


If you try to take the logarithm of a zero or negative number, an 
ILLEGAL QUANTITY error will occur. 





Generating Random Numbers: The Fk iD 
Function 


The built-in function kX ND produces random decimal numbers be- 
tween © and 1. The behavior of this function depends on whether the 
argument you give it is positive, Zero, or negative. 


The simplest way to use I ND is to give it a positive argument. R ND 
will produce a different random number each time you call it with a 
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Positive argument produces a different 
random number each time 


Zero argument repeats same result as 
previous Call 


Negative argument starts new, repeat- 
able sequence 


seed: the value used to begin a 
sequence of random numbers 


positive argument. The actual numeric value of the argument is ig- 
nored; only its sign is significant: 


RND ¢€1) —yields -431448496 
RND (1) —yields » 7335966024 
RND (99) —yields »- 343445325 


If you give R ND a zero argument, it will reproduce the same result as 
at the previous call: 


RND (39) —yields »270011996 
RND (0) —yields »2£70011996 
RND (0) —ylelds «470011956 
RND (38) —yields ,- 139756248 
RND (0) —yields -139756248 


Calling k ND with a negative argument causes it to begin a new, re- 
peatable sequence of random numbers. This is called seeding the 
random number generator; the particular negative value you use for 
the argument acts as a “seed” for the new sequence. Different seeds 
will produce different sequences, but each time you use the same 
seed you will get the same result. Subsequent calls to F ND with posi- 
tive arguments will then produce the same sequence of results: 


RND ¢€—-1) —yields2.,S3919G472E-08 

RND ¢1) —ylelds » 738207302 

RND (1) —yields .2/72707136 

RND ¢1) —yields .-2£99733446 

eNO (— 2) —yields 3. 73720468E-08; 
Starts new sequence 

RND ¢1) —yields .407457285 

RND ¢1) —yields -463740324 

RND ¢1) —yields + 387195686 

RND ¢—-—1) —yields2.9S9i19G6472E-08; 
repeats same sequence as 
before 

RND ¢1) —yields «738207302 

RND (¢1) —yields .272707136 

RND (1) —yields «299733446 


Scientific Notation: The suffix E - 08 in some of the random values 
listed above means “times 10 to the minus-8th power,” and is an exam- 
ple of the scientific notation that Applesoft uses to display certain num- 
bers. See Section |.2 for further details. 
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2.4.3 


DEF FN defines anew function 


argument: the value on which a function 
operates 


Formula limited to 239 characters 


Argument must be a real variable 


Ag 


Defining Your Own Functions: The DEF FN 
Statement 


DEF FN CUBE (AK) = K *® K *® & 


In addition to the built-in functions discussed in Sections 2.4.1 and 
2.4.2, Applesoft gives you the ability to define your own functions for 
the special needs of a particular program. Defining your own func- 
tions can be a real time-saver: instead of writing out the same com- 
plex formula over and over again, you can simply define it once as a 
function, give ita name, and then refer to it by that name whenever 
you need it. 


To define a function of your own, use the DEF FN statement. This 
statement consists of the keywords DEF FN (for “define function”) 
followed by the name of the function you're defining, the argument 
name enclosed in parentheses, an equal sign (=), and the formula 
defining the function. The examples below define functions to convert 
temperatures from Fahrenheit to Celsius and vice versa, and to con- 
vert angles from degrees to radians and vice versa, assuming that 
the value of the variable Plis3.14139263: 


10 DEF FN FTC (T) = (T - 32) * 5 / Q 
—Fahrenheit to Celsius 


£0 DEF FN CTF (T) = T * (9 / 8) + 32 
—cCelsius to Fahrenheit 


30 DEF FN DTR (A) = A * (PI / 180) 
—degrees to radians 


40 DEF FN RTD (A) = A * (180 / PT) 
—radians to degrees 


For example, the definition above for function F TC says “to convert 
from Fahrenheit to Celsius, take the value of the argument (T), sub- 
tract 32, multiply by 3, and divide by 9.” 


The formula defining a function must not exceed one program line (239 
characters) in length. 


The names you give to your functions must follow the same rules 
given in Section 2.1.1 for variable names: the name may be as long 
as you like (up to 239 characters), but Applesoft uses only the first 
two characters to distinguish one function from another. The argu- 
ment variable in the function definition must be a real variable— 
integer and string variables (ending in % or #) are not allowed. 
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Don’t begin function names with the 
same first two characters 


Calling defined functions 


Take care not to begin the names of different functions with the same 
two characters. Applesoft will consider the names CODF ISH and 
COUNT, for example, to refer to the same function, since they both be- 
gin with the same two characters. If you try to define functions with these 
two names, the second definition will redefine the function, causing the 
first definition to be forgotten. 


However, a program can have a function and an array beginning with the 
same two characters (or even having exactly the same name). This is 
because references to the function are written with the keyword F N (see 
below), but references to the array aren't. Thus Applesoft can tell that, 
for example, 


FN COUNT (N) 


is acall to the function named COUNT, whereas 


COUNT (N) 


is areference to the array of the same name. 


The DEF FN_ statement can be executed only from within a pro- 
gram; you can't use this statement in immediate execution. 


To call a function that you've defined with DEF FN, type the key- 
word F N (for “function”) followed by the name of the function and an 
expression in parentheses representing the argument value on 
which you want the function to operate. For example, using the func- 
tions defined above, 


PN FI (38s6) —convert 38 . & degrees Fahr- 
enheit to Celsius; yields 37 

FN CTF (100) —convert 1 00 degrees Celsius 
to Fahrenheit; yields 212 

FN DTR (180) —convert 1 8 degrees to radi- 
ans; yields 3.14139265 

FN RTD (PI / 2) —convertPI / Zradiansto 


degrees; yields 30 


Notice that the keyword F N must be used in calling your own defined 
functions, but not for built-in functions (see Section 2.4.1, “Built-in 
Arithmetic Functions”). 
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Unconditional Branching: The GOT 0 Statement 
Conditional Branching 

3.2.1 The ON...GOTO Statement 

3.2.2 The IF...THEN Statement 
Loops 

3.3.1 The FOR Statement 

3.3.2 TheNEAT Statement 

3.3.3 Nesting of Loops 

Subroutines 

3.41 The GOSUB Statement 

3.42 The RETURN Statement 

3.43 The ON...GOSUB Statement 
3.4.4 The POP Statement 

Error Handling 

3.5.1 The ONERR...GOTO Statement 
3.5.2 TheRESUME Statement 

3.5.3 Restoring Normal Error Handling 
Program Termination 

3.6.1 The STOP Statement 

3.6.2 The END Statement 
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Control statements determine the 
order of program execution 


unconditional branching: see 


Section 3.1 


conditional branching: see Section 3.2 


loops: see Section 3.3 


subroutines: see Section 3.4 


error handling: see Section 3.5 


program termination: see Section 3.6 


Control Statements 


Ordinarily, Applesoft programs are executed sequentially, from the 
lowest-numbered line to the highest. Contro/ statements allow you to 
branch to another part of the program: that is, to alter the normal or- 
der of execution and send control to a line of the program other than 
the next line in sequence. This ability to change the course of pro- 
gram flow is what gives computer programs their real power and 
flexibility. 


Section 3.1, “Unconditional Branching: The GO TQ Statement,” deals 
with the GOTO statement, which sends control unconditionally to a 
specified line of the program. 


Section 3.2, “Conditional Branching,’ discusses conditional branch- 
ing statements, which allow the program to decide what to do next by 
evaluating an expression or testing for a condition. 


Section 3.3, “Loops,” covers statements that are used in loops (por- 
tions of a program that are executed many times repeatedly). 


Section 3.4, “Subroutines,” deals with the very important subject of 
subroutines: sections of a program that can be executed on request 
from elsewhere in the program to perform some particular task. 


Section 3.5, “Error Handling,” describes Applesoft’s facilities for de- 
tecting and dealing with error conditions that arise during the execu- 
tion of a program. 


Finally, Section 3.6, “Program Termination,” covers the various ways 
of terminating (ending) the execution of a program. 
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unconditional branch: a branch that 
does not depend on the truth of any 
condition 


(GOTO branches to a specified line 
number 


infinite loop: a section of a program that 
will repeat the same sequence of actions 
indefinitely 


50 


Unconditional Branching: The GOTO 
Statement 


GOTO 


100 


An unconditional branch sends control to a specified line of the pro- 
gram without reference to whether any particular condition holds. 
Applesoft has two statements that cause an unconditional branch: 
GOTO and GOSUB. The GOTO statement is described in this sec- 
tion; see Section 3.4.1 for a description of the GOSUB statement. 


The GOTO statement interrupts the normal sequential execution of 
program lines and forces execution to branch to (go to) a specified 
line number. The branch is unconditional: that is, it doesn’t depend on 
the truth or falsity of any particular condition. 


For example, consider the following program: 


LOG PRINT “HELLO* —display the word HELLO 
©£O PRINT "THERE" —display the word THERE 
30 GOTO 10 —branch to line 1 © 

40 PRINT “FRIEND” —this line never executed 


This program displays the word HELLO onthe screen (line 1 ©), dis- 
plays the word THERE (line 2), and then (line 30) goes back to 
line 1 © to repeat the process. The word F Ik TEND never gets dis- 
played, because program execution never reaches line 4. Instead, 
the program simply repeats lines 1 © to 30 indefinitely, displaying the 
words HELLO and THERE over and over again on the screen. 


The program above contains an example of an infinite loop. To stop the 
program and regain control of the computer, press | conTrot |-C. 


If your program attempts to branch to a nonexistent line, or ifa GOTO 
statement does not include a line number, an error message such as 
TUNDEF ‘D STATEMENT ERROR IN 30 


will appear, identifying the program line in which the error occurred. The 
program will stop and Applesoft will return to command level: 


10 PRINT "Se oO 

20 PRINT. "THERE" 

=0 GO010 15 —branch to non-existent line 
40 PRINT *FRIEND" 
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3.2 


conditional branch: a branch that de- 
pends on the truth of a condition or the 
value of an expression 


ON...GO TO statement: see Section 
3.2.1 


ON...GOSUB statement: see Section 
3.4.3 


IF...THEN statement: see Section 
3.2.2 


3.2.1 


ON...GO TO chooses where to branch 
depending on the value of an 
expression 


lf value out of range, control proceeds 
sequentially 


You Can’t Branch to a Variable: If you attempt to use a variable instead 
of an actual line number to specify the line to which a branch should oc- 
cur(asinGOTQ J), Applesoft will always attempt to branch to line 
number ©, no matter what value the variable holds. If line © doesn’t ex- 
ist, anUNDEF ’D STATEMENT error will occur: 


© LE] 2 = 10 —assign value to variable 
10 PRIN? "HELLO 
20 PRINT "THERE ” 
20 GUIU 2 —Applesoft will try to go to line 
number © 
a0 PRIN] “FRIEND” 


Conditional Branching 


A conditional branch decides what action to take next, depending on 
the truth of a stated condition or on the value of an arithmetic expres- 
sion. Applesoft has three statements that cause a conditional branch: 


@e ON...GOTO branches to one of anumber of possible program 
lines, depending on the value of an arithmetic expression. 


e ON...GOSUB branches to one of anumber of possible subrou- 
tines, depending on the value of an arithmetic expression. 


@ IF...THEN either executes or skips one or more statements, 
depending on the truth of a stated condition. 





The ON...GOTO Statement 


ON X GOTO 130, £00, 
ON S54 - 7 GOTO 300, 


310} 
Zao} 


310; 
GOO + 


Lie ¢ 
130 


8s 


The ON...GO TO statement sends control to one of a list of line num- 
bers, depending on the integer value of an arithmetic expression. The 
expression between the keywords ON and GOTO is evaluated; if the 
result is real it is truncated to an integer. If this value is between i and 
the number of line numbers in the list, program execution branches to 
the line number at the corresponding position in the list. (For exam- 
ple, if the integer value of the expression is 3, execution branches to 
the third line number in the list.) If the integer value of the expression 
is © oris greater than the length of the list, execution continues with 
the next statement following the ON...GOTOQ. 
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3.2.2 


IF... HEN executes or skips, de- 
pending on the truth of a condition 


52 


The following program illustrates the use of ON...GOTO: 


10 INPUT «a —get number from keyboard 
£0 ON az GOTO 150; 200; G1idO, Bid; 150, 999 
—decide where to go, depend- 
ing on value of x 
30 PRINT "VALUE OUT OF RANGE, PLEASE 
RE tyres” —control comes here if X = or 
X>6 
40 GOTO 10 —start again 
130 PRINT "VALUE IS 1 OR 5" 
—control comes here if X = lor 
K=3 
iGO GOTO 10 
£00 PRINT "VALUE IS 2" 
—control comes here if = 2 
£10 GOTO 10 
310 PRINT "VALUE IS 3 OR 4" 
—control comes here if X = Sor 
A= a 
320 GOTO 10 
dog CAND —control comes here if * = 6 


If the integer value of the expression between ON and GOTO is less 
than 0 or greaterthan233,an ILLEGAL QUANTITY errorwill 
occur and program execuiion will halt. 





The IF... HEN Statement 


i; or soo THEN END 
IF HA - 23 2 SM - TTL THEN K% = 
HA - 239 2 HA = QO 
IF A (I) = 12 THEN GOTO 325 
IF AS . BS THEN 300 
iF <0 *93) AND NOT CE i] GOTO 21350 





The IF... THEN statement tests for the condition given between the 
keywords IF and THEN. If the condition is true, the statement or 
statements following T HEN in the same program line are executed. 
lf the condition is false, the remainder of the line following THEN is 
skipped and execution continues with the next program line in 
sequence. 
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When the statement following THEN is a GOTO, either (but not both) of 
the keywords THEN and GOTO may be omitted. The following state- 
ments are all equivalent: 


IF X (1) = 12 THEN GOTO 3223 
I-F A (1) = i2 1HEN Ges 
TFA (1) = 12 GUIO G25 


Notice that when the IF condition is false, program execution contin- 
ues with the next program line (not the next statement) in sequence. 
No other statements in the IF line are carried out: 





10 LET J = 1: K = 2 

£09 LET A = 10 A setto 10 here 

30 PRINT " J HOLDS “+ Js " AND K 
HOLDS "43 K 

40 IF A = 10 THEN J = S: K = 10: 
GOTO 100 —A is not greater than 1 0; test 

fails 

20 PRINT "THE VALUES OF J AND K ARE 

UNCHANGED, " —this message gets printed 


GO GOTO 999 

100 PRINT "J NOW HOLDS “35 Js " AND K 
HOLDS “3s K —this message not printed 

999 END 


When the program above is run, the I F testin line 4 will fail, the 
values of J and K will not be changed, and execution will continue 
with line 30. If line 20 were changed to 


20 LET A = 25 


then the IF test in line 4 would succeed, the values of J and K 
would be changed, and control would branch to line 100. 
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© means false 


Any nonzero value means true 





Using Numeric Valuesin IF...THEN: The IF...THEN staternent 
considers a numeric value of to mean “false”; any nonzero value is 
taken to mean “true.” Thus you can write statements such as 


IF J THEN GOSUB 400 

which is equivalent to 

IF J <> 0 THEN GOSUB 400 

Recall also that Applesoft’s relational and logical operators always yield 
a value of i for true and © for false. Thus you can combine numeric val- 
ues with the logical operators: the statement 

IF NOT J THEN GOTO 300 

is equivalent to 

IF J = 0 THEN GOTO 300 

and 

IF A AND B THEN END 

is equivalent to 

IF (A => 0) AND (B <3 0) THEN END 


Numeric values used in this way offer two advantages over the corre- 
sponding relational expressions: 


e@ They take up less space in memory. 


@ They execute somewhat faster. 


See Appendix G for further hints on making your programs more effi- 
cient. 


Curious Parsing: Applesoft gets confused if the keyword THEN is im- 
mediately preceded by a variable name ending in the letter A. For exam- 
ple, the statement 


IF J = BETA THEN 230 

will be interpreted as 

if 2 = GET At BENZ 

Causing a syntax error. This is because AT and THEN are both re- 
served words; in the example, the word AT is encountered first, so it is 
interpreted first. Such is life with Applesoft. You can get around the prob- 


lem by using parentheses: 


IF (J = BETA) THEN 230 
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3.3 


loop: a sequence of statements exe- 
cuted repeatedly 


pass: a single execution of a loop 


index variable: a variable whose value 
changes on each pass through a loop; 
often called control variable or loop 
variable 


NEXT statement: see Section 3.3.2 


body: the statements in a loop between 
the FOR and NEXT statements 


Loops 


A loop is asequence of statements in a program that are executed 
repeatedly, often with the value of some variable being changed on 
each pass through the loop. Loops are fundamental to all computer 
programming: it’s practically impossible to write any kind of useful or 
interesting program that doesn't include at least one loop. 


The usual way of writing loops in Applesoft is with the F OR and 
NEXT statements. The F OR statement marks the beginning of the 
loop. It identifies the loop’s index variable (the variable whose value 
changes on each pass) and gives the starting and ending values the 
index variable is to take on. Sometimes it also specifies the amount 
by which the value of the index variable is to change on each pass 
(see Section 3.3.1, “The F OR Statement,” for details). 


The NEXT statement marks the end of the loop and causes the loop 
to be executed again for the next value of the index variable. When 
the loop has been executed once for each value of the index variable, 
as specified in the F OR statement, control “falls through” to the next 
statement following the NE #T statement. (That’s right, “the next 
statement following the NE « T statement.”) 


Here’s an example to show how loops work: 


> PASS = Q —initialize pass count 
190 FOR ~ = 3 TO 10 —execute loop once for each 
value of x from 3 to 10 
209 PASS = PASS + 1  —countpasses through the loop 
30 PRINT "PASS #"3 PASS 
—display pass count 
40 PRINT "“INDEA = "4 & 
—display current value of index 
variable * 
20 PRINT —display blank line (for 
neatness) 
GO NEAT & —repeat loop for next value of * 
70 PRINT "LOOP FINISHED" 
—control comes here after last 
pass through loop 
80 END 


The loop begins with the F OR statement in line 1 ®, which specifies 
that the loop is to be executed once for each value of index variable * 
from 3 to 10. Lines 20 to 30 form the body of the loop. The NEAT 
statement in line G® marks the end of the loop and sends control 
back to line 2 for the next value of “. After the loop is executed for 
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Be careful jumping out of loops 
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the last time, with 4 set to the specified ending value of 10, 4% isin- 
creased to i 1. Since this exceeds the ending value, contro! “falls 
through” the NE XT statement to line 7. 


When the program above is executed, it will display the following 
results on the screen: 





Loop Before You Leap: Exiting from the middle of aF OR/NE XT loop 
before the index variable reaches the ending value leaves Applesoft ex- 
pecting a resolution that never comes. This is a dangerous practice that 
Can Cause unpredictable results in your program’s execution. Don’t write 
loops of the form 


10 FOR INDEX = LOW TQ HIGH 

20 Le! COUNT = COUNT + 1 

20 IF COUNT = LIMI?T THEN GOTO 100 
—not recommended 

MO NEAT INDEX 


To be on the safe side, it’s better to finish the loop this way: 


JO IF COUNT = LIMIT? THEN INDEX = HIGH: 
NEAT INDEA: GOT 100 
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3.3.1 


F OR marks the start of a loop 


index variable: a variable whose value 
changes on each pass through a loop; 
see Section 3.3, above 


step value: the amount by which the 
index variable changes on each pass 
through a loop 


The FOR Statement 


FOR ¥ = 1 TO 10 

FOR MASS = 3.53 TQ 7 STEP 1.5 

FOR YEAR = 1980 TO 1960 STEP —-4 
FOR Vo = A + 2 TO 2*B - 3 STEP C / 2 


The FOR statement marks the beginning of a loop, identifies the 
loop’s index variable, and gives the starting and ending values of the 
index variable. It may also optionally specify the step vaiue, the 
amount by which the value of the index variable is to change on each 
pass through the loop. If no step value is given, a value of i is 
understood. 


In the example in Section 3.3 above, no step value was given, so the 
index variable “4 was incremented by 1 on each pass through the 
loop. If line 1 © in the example were changed to 


10 FOR kK = 3 TO 10 STEP @ 
—execute loop once for each 
value of * from 3 to 10 by = 


the program would produce the following output on the display 
screen: 





The loop is executed four times, with the index variable taking on val- 
ues of 3, 3, 7, and 9. Atthe end of the fourth pass, the index variable 
exceeds the specified ending value (2 plus 2 is i 1, whichis greater 

than the ending value of i ©), so the loop ends and execution contin- 

ues with the statement following the NE XT inline G®. 
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Body of loop always executed at least 
once 


Step value may be negative 


Index variable must be a real variable 
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Applesoft Will Try Anything Once: Notice that the test to see whether 
the index variable exceeds the ending value is carried out at the end of 
the loop. This means the body of the loop will always be executed at 
least once. Even if the specified starting value is greater than the ending 
value, asin 


10 FOR XK = 10 TO 3 —starting value exceeds ending 
value 


it won't be discovered until after the loop has been executed once (1 0 
plus i is 1 1, whichis greater than 3). 


It’s also possible to specify a negative step value: 


10 FOR K = 10 TQ 3 STEP —é2 
—negative step value 


In this case the index variable will take values of 10,8, 6, and 4. 
When the step value is negative, the loop ends when the index value 
becomes /ess than the ending value (4 plus — = is =, whichis less 
than the ending value of 3). Notice that the starting and ending val- 
ues have been reversed; if the statement read 


iQ FOR XH = 3 T0 10 SIeEP =z 
—starting value less than ending 
value 


the loop would have been executed only once (3 plus — 2 is 1, which 
isless than 1). 


A step value of © will result in an infinite loop. To stop the program 
and regain control of the computer, press [ contro |-C. 


The index variable specified in a F OR statement must be a real vari- 
able. Attempting to use an integer variable, such as 


10 FOR ~“A = 3 TQ i0 —~integer index variable 
will cause a syntax error at run time. (However, the expressions for 


the starting, ending, and step values are unrestricted; any or all of 
these values may be specified by an integer variable). 
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3.3.2 


NEXT repeats execution of a loop 


3.3.3 


nested loop: a loop contained within the 
body of another loop 


The NEXT Statement 


NEAT 
NEAT INDEA 
NEAT Jol 


The NEXT statement marks the end of a loop and causes the loop to 
be repeated for the next value of the index variable, as specified in 
the corresponding F OR statement. When the value of the index vari- 
able becomes greater than the specified ending value (less than the 
ending value if the step value is negative), execution proceeds with 
the statement immediately following the NE *T statement. 


Naming the index variable ina NEAT statement is optional; if you 
omit it, Applesoft will automatically repeat the most recently entered 
loop. If you’re using nested loops, this means the innermost loop con- 
taining the NE + T statement will be repeated. 


Helpful Hint: Leaving out the index variable in NE XT statements will 
make your programs run slightly faster: 


10 FOR G = 1 [U & 
20 PRINT “WOWs MOM!” 
30 NEAT —no index variable necessary 





Nesting of Loops 


F OR/NEXT loops can be nested one inside another to a maximum 
depth of ten levels. For example, 


10 FOR A = 1 TO 3 —start of outer loop 
20 FOR B = 1 7T0 2 — start of inner loop 
30 PRINT "@ = "35 As "+B = "5 B 
—display values of index 
variables 
40 NEXT B —repeat inner loop 
20 NEAT A —outer loop not repeated until 


inner loop is finished 
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No more than 10 levels of nesting 


Don’t cross loops 
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The inner loop (lines 2 © to 4) is executed twice for each pass 
through the outer loop; the PR INT statement in line 30 is executed 
six times in all. This program will display the following on the screen: 





A= i+ B= 2 
Beer ei 

be 
As e-] 


Although this example shows only two levels of nesting, Applesoft al- 
lows as many as ten levels (a loop inside a loop inside a loop... ten 
times). If you nest your loops to a depth greater than ten, your pro- 
gram will halt with the error message 


OUT OF MEMORY 


Nested loops must not cross each other—that is, each loop must be 
completely contained within the body of the next outer loop. Once a 
loop is started using a particular index variable, the corresponding 
NEXT must name the same index variable (if it names any at all). In 
the example above, if lines 40 and 30 were reversed 


40 NEAT A —attempt to repeat outer loop 
20 NEXT B —before inner loop is finished 


the program would halt with an error because of the crossed loops. 


Warning 


Cross-looping is a second-degree misdemeanor punishable by five min- 
utes inthe penalty boxanda NEXT WITHOUT FOR error. It will 
also melt your keyboard. 


When two or more NE XT statements occur in a row, as in the example 
above, you can combine them into a single NE XT statement of the form 


40 NEXT B:+A —repeat inner, then outer loop 
Notice, however, that the index variables must be listed in the reverse or- 
der of their corresponding F OR statements, to avoid crossing loops. The 
statement 

40 NEXT A+B —whoops! 


will reduce your keyboard to a puddle of plastic. 
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3.4 


GOSUB statement: see Section 3.4.1 


RETURN statement: see Section 3.4.2 
ON...GOSUB statement: see Section 


3.4.3 


POP statement: see Section 3.4.4 


GOTO statement: see Section 3.1 


point of call: the point in a program from 
which a subroutine is called 





Subroutines 


A subroutine is a section of a program that can be executed on 
request from another part of the program. Applesoft has four state- 
ments relating to subroutines: 


(, OSUB directs control to a particular subroutine. 


FkE T URN sends control back to the statement following the 
(;0SUB that branched to the subroutine. 


ON...GOQSUB selects one of anumber of possible subroutines, 
depending on the value of an arithmetic expression. 


POP removes a return address from the top of the control stack 
(see the box below titled “How Subroutines Stack Up”). 


To call a subroutine (request its execution), branch to its first line with 
a GOSUB statement. GOSUB differs from an ordinary GOTO in that 
it “remembers” where in the program the subroutine was called from, 
so that control can return to that point when the subroutine is finished. 
The same subroutine can be called from many different places in the 
program; when the subroutine is finished, it sends control back to the 
statement following the proper point of call by executinga RETURN 
statement. 


Here’s an example to illustrate the idea: 


Pd 
| 


10 FOR i TO 10 —execute loop 10 times 
20 LET A INT (RND (1) * 100) 
—generate a random integer be- 
tween © and 39 
30 PRINT xX " IS “4 —display first part of message 
40 IF K < 30 THEN GOSUB 1000 : GOTO GO 
—branch to subroutine at line 
1000 if random number is 
less than 30; on return, go to 
line 60 
20 GOSUB 2000 —branch to subroutine at line 
= 00 if random number is 
~ or greater 


GO PRINT "PASS #"3 2: PRINT 


—count number of passes 
through loop 
70 NEXT 2 —repeat loop 
goo EN —end program 
1000 PRINT "LESS THAN 309" 


Subroutines 


—print second part of message 
for numbers less than 30 





1o10 


2000 


2O10 


RETURN 


PRINT 


RETURN 





—return to statement following 
point of call 
“MORE THAN 49" 
—print second part of message 
for numbers greater than 48 
—return to statement following 
point of call 


The loop in lines i @ to 7@ generates a random integer between © 


and £9, then calls one of the two subroutines at lines 1000 and 

= OO, depending on the value of the random number. Each of the 
subroutines displays an appropriate message, then returns control to 
the statement following the point of call witha RE TURN statement 
(lines 1010 and 2010). The program then displays a count of the 
number of passes through the loop and repeats the loop from the be- 
ginning. When the loop has been executed ten times, the program ends. 


Control returns to statement (not line) 
following GOSUB 


Notice that the KE TURN statement returns control to the statement 
following the GOSUB statement, not just to the /ine following it. In line 


4 of the example above, if the random number generated is less 
than 3, control is directed to the routine at line 1 000.When execu- 
tion returns from the subroutine, it will continue with the statement 
GOTOQ 60, branching around line 30. 


Every subroutine should be regarded as a separate, indivisible unit 
of your program, which should be entered only witha GOSUB and 


Don’t use the back door 


exited only with a RE TURN. Jumping into or out of the middle of a sub- 


routine with an ordinary GOTO subverts Applesoft’s orderly control 
stack mechanism (see “How Subroutines Stack Up,” below) and causes 
the programmer to be in a state of sin. People who indulge in such 
odious practices should be ostracized from polite society. 


nested subroutine call: a call to a sub- 
routine from within another subroutine 


10 


Z\) 


3 


1Oooo 


itj]1 0 





GOSUB 
PRINT 


END 


PRINT 


GOSUB 


Subroutine calls may be nested: that is, you can call one subroutine 
from inside another. Consider the following program: 


1o00 


—branch to first subroutine 


"BACK HOME AGAIN" 
—this message displayed last 


—prevent control from acci- 
dently “falling into” a 
subroutine 


"FIRST SUBROUTINE CALLED" 
—this message displayed first 


2000 —hbranch to second subroutine 
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stack: a list in which entries are added or 
removed at one end only 


return address: the point to which con- 
trol returns on completion of a subroutine 


push: to add an entry to the top of a stack 


pop: to remove the top entry from a stack 


1020 PRINT "BACK AT FIRST SUBROUTINE" 
—this message displayed third 


1030 RETURN —return to statement following 
point of call (line = ©) 


£900 PRINT "SECOND SUBROUTINE CALLED" 
—this message displayed 
second 


£910 RETURN —return to statement following 
point of call (line 1 O20) 


Line i © calls the first subroutine, at line 1 ©. This subroutine dis- 
plays the first message on the screen, then (line i 1) calls the 
second subroutine at line = ©. The second subroutine displays its 
message, then returns control (line = @ 1 ©) to the statement following 
the point of call in the first subroutine. The first subroutine then dis- 
plays another message and returns control (line 1&3) to the state- 
ment following its point of call. The final message is then displayed 
(line =) and the program ends. The lines of the program are exe- 


cuted in the following order: 


Line 10 
Line 1000 
Line 1010 
Line 2000 
Line £010 
Line 1020 
Line 1030 
Line £0 
Line 30 


The program produces the following output on the screen: 


PIRS! SUBROUTINE CALLED 
SECOND SUBROUTINE CALLED 
BDACK Al FIRS! SUGKOUILINE 
BACK HOME AGAIN 


How Subroutines Stack Up: Applesoft maintains a contro! stack to - 

keep track of the return addresses—the points to which control is to — 
return on completion—for all subroutines in progress.Eachtimea 

GOSUB is executed, the location of the statement following the 

GOSUB is pushed onto the top of the stack. Whena RETURN state- — 

ment is executed, the top entry is popped from the stack and control is 

directed to that point in the program. This arrangement ensures that 

control enters and leaves subroutines in LIFO (last-in-first-out) order. 
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3.4.1 


GOSUB branches to a subroutine 


control stack: see Section 3.4 


GOTO statement: see Section 3.1 


3.4.2 


RETURN returns control froma 
subroutine 


control stack: see Section 3.4 





Subroutine calls can be nested up to 25 levels deep: that is, you can 
GOSUB fomaGOSUB fomaGOSuUB...24 times. Attempting to 
go more than 25 levels deep willresultinanQUT OF MEMORY 
error. 


Actually, you’re out of stack space, as opposed to program space. Since 
no rational BASIC program ever uses such complex nesting, this error 
usually means you've got a subroutine accidentally calling itself. 





The GOSUB Statement 
GOSUB iooo 


The GOSUB (for “go to subroutine”) statement is used to branch to 
a subroutine, saving a return address to which control can return 
when the subroutine is completed. The location of the statement im- 
mediately following GQSUB is pushed onto the control stack, and 
control is sent to the line number specified in the GOSUB statement. 
GOSUB differs from an ordinary GQT 0 in that it “remembers” where 
in the program the subroutine was called from, so that control can re- 
turn to that point with a RE T URN statement when the subroutine is 
finished. 


A GOSUB toa target line that doesn’t exist will cause a message such 
as 


PUNDER "DD Sia (EMeat ERRuR JH tase 


to be displayed, identifying the line number in which the error occurred, 
and your program will come to an untimely halt. 





The RETURN Statement 
RETURN 


The RE TURN statement returns control from a subroutine to the 
statement following its point of call. The top entry is popped off the 
control stack and control is sent to that return address. 


If the control stack is empty when RE TURN is executed, your program 
will halt with the message 


RETURN WITHOUT GOSUE 
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3.4.3 


ON...GOSUB chooses a subroutine 
depending on the value of an 
expression 


lf value out of range, control proceeds 
sequentially 


The ON...GOSUB Statement 
ON X GOSUB 150, 200, 


310+ 310+ 150+ 339 


ON S% - 7 GOSUB 300, 285+, 900, 130 


The ON...GQOSUB statement sends control to one of a list of subrou- 
tines, depending on the integer value of an arithmetic expression. 
The expression between the keywords ON and GOSUB is evaluated; 
if the result is real it is truncated to an integer. If this value is between 
1 and the number of line numbers in the list, program execution 
branches to the subroutine at the corresponding position in the list. 
(For example, if the integer value of the expression is 3, execution 
branches to the subroutine beginning at the third line number in the 
list.) If the integer value of the expression is © or is greater than the 
length of the list, execution continues with the next statement follow- 
ing the ON...GOSUB. 


The following program illustrates the use of ON...GOQSUB: 


10 INPUT A 
20 ON K GOSUB 150; 


—get number from keyboard 
200% 310+ 310+ 150, 


Sec —decide where to go, depend- 
ing on value of # 
30 IF K = 0 OR & G THEN PRINT "VALUE 


PLEASE RETYPE: ” 
—display message if * out of 


OUT OF RANGE; 


range 
40 GOTQ 10 —start again 
150 PRINT "VALUE I5 1 OR 3" 
—control comes here if X = i 
orx =5 
iG0 RETURN 
“O00 PRINT "VALUE IS 2" 
—control comes here if X = = 
210 RETURN 
310 PRINT "VALUE [IS 3 OR 4" 
—control comes here if X = 3 
OrA =a 


320 RETURN 
Heo cl —control comes here if Xk = & 
Compare the program above with the example given for the 
ON...GOTO statement in Section 3.2.1. The operation of 
ON...GOSUB is very similar to that of ON...GO TO, except that 
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RETURN statement: see Section 3.4.2 


3.4.4 


POP removes top entry from control 
stack 


control stack: see Section 3.4 








ON...GQSUB “remembers” where in the program the subroutine was 
called from by pushing onto the control stack the location of the next 
statement following ON...GQSUB. Control can then return to that 
point with a RE T UN statement when the subroutine is finished. 


If the integer value of the expression between ON and GOSUB is less 
than © orgreaterthan233,anILLEGAL QUANTITY errorwill 
occur and program execution will halt. 





The POP Statement 
POP 


The POP statement removes (pops) the top return address from the 
control stack without sending control to that point. This causes the 
next KE TUN statement to send control back to the statement fol- 
lowing the point of the second most recent subroutine call, instead of 
the most recent. 


Here's an example illustrating the use of POP: 
10 GOSUB 1000 —branch to first subroutine 


£9 PRINT "BACK HOME AGAIN" 
—this message displayed last 


30 END —prevent control from acci- 
dently “falling into” a 
subroutine 

1000 PRINT "FIRST SUBROUTINE CALLED" 
—this message displayed first 
1010 GOSUB 2000 —branch to second subroutine 


1020 PRINT "BACK AT FIRST SUBROUTINE" 
—this message never displayed 
1030 RETURN —this return never taken 
£900 PRINT “SECOND SUBROUTINE CALLED" 
—this message displayed 
second 
£003 POP —remove return address from 
stack 
£0910 RETURN —return to statement following 
first subroutine’s point of call 
(line 20) 


This program is identical to the one in Section 3.4 illustrating nested 


subroutine calls, except thata POP statement (line 2003) has been 
added to the second subroutine. The effect of the POP is to remove 


Control Statements 





Resist temptation 


3.5 


ONERR GOTO statement: see Sec- 
tion 3.5.1 


RESUME statement: see Section 3.5.2 


the second subroutine’s return address (line i @ = ©) from the control 
stack, causing the RE TURN in line 20 1 0 to go back to the state- 
ment following the point of call of the first subroutine (line =) in- 
stead. As aresult, lines 1 020 and 1030 are never executed, and 
themessage BACK AT FIRST SUBROUTINE is never dis- 
played. The lines of the program are executed in the following order: 


Line 10 
Line 1000 
Line 1010 
Line 2000 
Line 20058 
Line 2010 
Line 20 
Line 30 


The program produces the following output on the screen: 


PIRSI SUBROUTINE CALLED 
SECOND SUBROUTINE CALLED 
BACK HOME AGAIN 


If the control stack is empty when POP is executed, your program will 
haltwithaRETURN WITHOUT GOSUB error. 


Programming Tip: Although it’s sometimes tempting to try to get out of 
a tight programming situation by using POP, most good programmers 
avoid it, because it makes program flow really difficult to follow. If you 
find yourself becoming ensnared in convoluted code, 'tis a far better 
thing to redesign your program than to resort to the use of POP. See 
Chapter 8 for a tutorial on program planning. 


Error Handling 


Sometimes even the most carefully written program will come to an 
embarrassing halt at an inopportune moment because of an error. If 
you've never suffered an “error crash,’ you ain't a programmer. Ap- 
plesoft’s ONERR GOTO and RESUME statements provide a mech- 
anism for detecting program errors as they occur and dealing with 
them from within your program. Using these statements, you can 
make your program display its own error messages or take any other 
action you consider appropriate, instead of coming to a sudden, 
screeching stop. 
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3.5.1 


ONERR GOTO allows program to 
handle errors 


error code: a number representing a 
type of error 


Error code stored at location 222 


meanings of errors: see Appendix E 


Table 3-1 Error Codes 








The GNERR GOTOQ Statement 
ONERR GOTO 20000 


The ONERR GOTO statement turns off Applesoft’s normal error 
handling and replaces it with an error-handling subroutine in your 
program. After this statement is executed, program errors will no 
longer stop the program, but will instead transfer control to the error 
routine beginning at the specified line number. 


Before sending control to the error routine, Applesoft stores an error 
code identifying the type of error at a special location in the comptu- 
ter’s memory, location = 2. The error routine can then look at the 
contents of this location with the PEEK function and decide what ac- 
tion to take, depending on the error. Table 3-1 lists the possible error 
codes and their meanings. See Appendix E, “Error Messages,” for 
further information on the conditions that cause each type of error. 


Code Meaning Code Meaning 
O NEXT without FOR 120 | Redimensioned array 
16 Syntax 133 Division by zero 
2- RETURNwithout GOSUB 163 Typemismatch 
4= Outofdata 176 — String too long 
23 Illegal quantity 191i Formulatoo complex 
69 Overflow ad Undefined function 
7?  Outofmemory = <~4  Badresponseto INPUT 


statement 


255 [contro }C interrupt attempted 


90 Undefined statement 


107 Bad subscript 
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[ CONTROL |-C: see Section 1.3.2 


RESUME statement: see Section 3.5.2 


To prevent an error from interrupting the program, the ONERR 
GOTO statement must be executed before the error occurs. If you're 
using ONERR GOTO, it’s a good idea to make it one of the first lines 
in your program, as in the following example: 


10 ONERR GOTO 21500 
—establish error routine at line 
£1500 


21500 LET EC=PEEK (222 
—get error code 
21310 iF EC <> 255 THEN 21520 
—branch if not{ contrat J-C 
21520 PRINT "SORRY--PROGRAM CAN‘’T BE 
STOPPED WITH CONTROL-C" 
—if user pressed[ CONTROL J-C, 


display special message 


21530 RESUME —and resume program 
21550 PRINT “UNANTICIPATED ERROR: 
CODE “+s EC —on any other error, display 
general message 
2loev SIUF —and halt 


The program above uses its own error-handling routine to prevent the 
user from interrupting execution by pressing [ conTROL |-C. Line 10 
turns off Applesoft’s normal error handling and substitutes instead 
the program’s own error routine, beginning at line 2 1300. If an error 
later occurs, the first thing the error routine does (line = 1300) is get 
the error code from memory location = = = to find out what type of er- 
ror occurred. The error code is assigned to variable EC to make it 
easier to handle. Line 2 1 51 tests for an error code of #35, mean- 


ing “ -C interrupt attempted” (see Table 3-1). If the error is 
a[{ CONTROL |-C, the message 





is displayed on the screen (line 2 1 30) and control is sent back to 
the point of the error with the RESUME statementin line 21330. 


Ifthe errorisn’ta[{ contro J-C, the IF...THEN testinline 21510 


sends control to line 2 133. Since the error routine has no special 
action to take for any of these other errors, and since Applesoft’s nor- 


Error Handling 








Cover all the bases 


PEEK function: see Section 7.1.1 


For more information... 


NoONERR GOTO inimmediate 
execution 


3.5.2 


kESUME returns control from an 
error routine 
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mal error messages are not being displayed, the error routine just 
displays a general error message such as 


UNANTICIPATED ERROR; CODE 16 


(for a syntax error) and stops the program. 





Warning 


Once anONERR GOTO statement has been executed, ordinary error 
messages will not be displayed and the program will not stop if an error 
is detected. If your program’s own error routine doesn't take some ap- 
propriate action (such as stop) for every possible error code, the pro- 
gram may hang indefinitely or exhibit other forms of deviant behavior. 
Make sure your error routine tells the computer what to do in all possible 
cases of error; see the following box for suggestions. 


More Peeking: In the program above, the general error message dis- 
played in line 2 1 33 would be more useful if it included the line num- 
ber where the error occurred as well as the error code itself. Through the 
magic of the PEEK function, the following two lines (replacing line 

= 1330 ofthe original example) will do the trick: 


ZiveO EL = PEEK (21S? * 296 + PEEK C213) 
—get error line 
21555 PRINT "UNANTICIPATED ERROR; CODE "5 
ELS ~* 20 Lae © Bae 
—display general error message 


For an even nicer way of handling unanticipated errors, see Section 
3.5.3, “Restoring Normal Error Handling.” See Appendix F, “Peeks, 
Pokes, and Calls,” for more astounding feats of sorcery and witchcraft 
you can perform at home. 


The ONERR GOTO statement can be executed only from within a pro- 
gram; you can't use this statement in immediate execution. 





The RESUME Statement 
We OME. 


The RESUME statement returns control from an error-handling rou- 
tine to the statement in which the error occurred. It should be used 
only in error routines, and should never be encountered in the normal 
flow of control. 
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Don’t leave a mess! 


control stack: see Section 3.4 


GOTO statement: see Section 3.1 


CALL statement: see Section 7.1.3 


A 


Don’t use RESUME in immediate 
execution! 


3.5.3 


POKE 216 +0 restores normal error 
handling 


POKE statement: see Section 7.1.2 


Warning 

If Applesoft encounters a RESUME statement without an error having 
occurred, the program may stop or hang indefinitely, or other unpredict- 
able but probably unpleasant events may transpire. 


Warning 

Notice that k ESUME sends control back to the same statement that 
caused the error in the first place. If the same error occurs again, the 
program may hang in an infinite loop. Similarly, if an error occurs within 
the error-handling routine itself, RESUME will cause the program to 
hang. 


Cleaning the Stack: When an error occurs whileanONERR GOTO 
statement is in effect, Applesoft pushes certain information onto its inter- 
nal control stack before transferring control to the error routine. When 
you leave the error routine witha RESUME statement, these control 
codes are automatically popped off the stack. But if the error routine 
ends with a GOTO instead of a RESUME, the control codes will remain 
behind on the stack, probably causing the world to end with a whimper 
later on. To avert a global catastrophe, always “clean up” the stack by 
uttering the magical incantation 


CALL — 3288 


before leaving an error routine with a GOTO statement. 


Warning 


The RESUME statement should be executed only from within a pro- 
gram. Attempting to use this statement in immediate execution may 
Cause a syntax error, cause the system to hang, or begin executing an 
existing or even a deleted program. 





Restoring Normal Error Handling 


You can restore Applesoft’s normal error-handling mechanism by 
using the POKE statement: 


POKE 216,0 
After executing this statement, Applesoft will go back to stopping the 


program when an error occurs and displaying its usual error 
messages. 
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Apple Ile Monitor program: see Apple 
lle Reference Manual 








One use of this technique is to prevent your program from hanging or 
falling into the Monitor in case an error occurs in the error-handling 
routine itself. You can do this by restoring normal error handling with 
POKE 216 +0 atthe beginning of your error routine, then reacti- 
vating the error routine with ONERR GOTO before returning to the 
main program. Here’s another version of the example program of 
Section 3.5.1 that illustrates this technique: 


10 ONERR GOTO 213500 
—establish error routine at line 


21300 
21500 POKE £16;0 —restore normal error handling 
24503 LET EC=PECR tece 
—get error code 
eiewi@ IP EL 42 gone THEN £1380 


— if not { conTrov |-C, resume 


program under normal error 
handling 


PRINT "SORRY--PROGRAM CAN’T BE 
STOPPED WITH CONTROL-C*" 
—if user pressed[{ contro J-C, 
display special message, 
21530 ONERR GOTO £1500 
—reactivate this error routine, 


PJ 
fooeste 
ey 
PJ 


eee RESUME —and resume program 


This program also illustrates another applicationof POKE 21670. 
Notice that if the error is anything other than a[ contrat |-C interrupt 
(code #33), the IF...THEN testin line = 13 10 sends control di- 
rectly to the RESUME statementin line = i340, without executing 
theONERR GOTO inline 21539. The effect of this is to re-exe- 
cute the statement containing the original error, but with Applesoft’s 
normal error handling still in effect. This will cause the same error to 
occur again, but this time Applesoft will display its normal error mes- 
sage and halt the program. Thus -C is the only error that 
gets special handling; all other errors produce the same results as if 
there were no special error routine. 
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3.6 


debugging: finding and correcting errors 


in a program 


3.6.1 


STOP halts the program and displays 


a message 


CONT command: see Section 1.3.3 


END halts execution quietly 


END optional at end of program 


3.6.2 


Program Termination 


The STOP and END statements are used to halt the execution of a 
program. The only difference between them is that 5 TOP displays a 
message giving the number of the line at which execution was halted; 
this information is useful primarily for debugging purposes. END sim- 
ply stops the program without any message, and is usually used ata 
program's natural finishing point. 





The STOP Statement 
STOP 


The STOP statement halts execution of the program and displays a 
message giving the number of the program line in which the 5TOP 
occurs. For example, the line 


lio STGP 

displays the message 

BREAK IN i115 

Applesoft returns to its command level, allowing you to enter new 
lines, examine or change the values of variables, and so on. You can 


then resume the execution of the program using the CONT 
command. 





The END Statement 
END 


The END statement halts execution of the program and returns con- 
trol to Applesoft’s command level. No message is displayed on the 
screen; program execution just stops quietly. 


SSS END 


An END statement is purely optional at the end of a program. The pro- 
gram will end by itself, even without an END statement, when it runs out 
of statements to execute. 


Program Termination 
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4.1.1 The DIM Statement 
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4.2.2 The LEN Function 
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4.2.5 String Conversion Functions 
The STIk$ Function 
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The CHR $ Function 
The ASC Function 











arrays: see Section 4.1 


strings: see Section 4.2 


4.1 


array: a collection of variables referred to 
by the same name 


element: one of the individual variables 
in an array 


simple variable: a variable that is not an 
element of an array 


Arrays and Strings 


This chapter discusses two important forms of data that Applesoft 
programs can operate on: arrays and strings. Both topics were 
treated briefly in Chapter 2, “Variables and Arithmetic,’ but are cov- 
ered in more detail here. 


Section 4.1, “Arrays,” deals with collections of related information of 
any type (real, integer, or string), referred to by the same name and 
distinguished by means of numerical subscripts. 


Section 4.2, “Strings,” describes Applesoft’s facilities for manipulat- 
ing strings of characters such as words or names: comparing them, 
concatenating (chaining) them together, taking them apart, and con- 
verting them to and from numeric values. 


Arrays 


An array is acollection of variables referred to by the same name, 
usually holding a collection of data items that are related to each 
other in some logical or systematic way. The individual variables in 
the array are called its elements, and are distinguished from one an- 
other by means of identifying index numbers called subscripts. 


An array can be of any type: integer, real, or string. Array names fol- 
low the same rules as simple variable names of the same type. To re- 
fer to a particular element of an array, write the array name followed 
by one or more subscripts, separated by commas and enclosed in 
parentheses. The subscripts refer to the position of the desired ele- 
ment within the array: 


QO (6) —element & of real array 9 
FIGURE” (N) —element N of integer array 
FIGURES 
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Figure 4-1 A Real Array 


Array F 


nm (Oo) 
R Cl) 


Rta) = 


Rta) 


Figure 4-2 A String Array 





—R(S+2) 





NAMES (J - 3) —elementJ - S3ofstring 
array 


COUNT (SUNA¢ 2) —element (SUMZ; 2) ofreal 
array COUNT 


Figure 4-1 shows areal array named F with five elements, numbered 
Oto 4. Element Fk ( O ) (pronounced “R-sub-zero”) holds the value 
23,R¢1) holds 27.33, andsoon. Ifthe value of variable 5 is 2, 
then the expression Rk (5) refers to element Ft ¢ 2 } , whose value is 
31.4,andtheexpressionk(S + £) referstoelement hk (4), 
which holds the value i 3. 


Ancther example is shown in Figure 4-2, this time a string array 
named NAME $ with seven elements, numbered © to &. Element 
NAME (1) holds the string value "SCOT", NAMES (3) holds 
the value "BRUCE", NAMES(6) holds "MEG", andsoon. Ifthe 
value of variable C4 is 3, then the expression NAME (C%) refers to 
element NAME (3 ),whosevalueis "J.D. ", andthe expression 
NAMES(C%Z - 3) referstoelement NAME ¢ 2), which holds the 
value "BITZEL". 


Array NAME $ 


me i 





NAMES (0) — 





NAMES (1) — 






NAMES (2) — <— NAMES (CL — 3) 






NAME$ (3) — 






NAMES (4) — 





NAMES (3) — <— NAMES (CZ) 





NAME (6) — 
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4.1.1 


D IM defines the size of an array 


dimension: the maximum size of one of 
the subscripts of an array 


Available memory limits size of arrays 


Subscripts start from 0, not 1 





The DIM Statement 


DIM RK (4) 

VIM TLILES 
DIM HS (JA) 
DIM MARKA (3+ 


(100) 


~ ff DF F 


The DIM (for “dimension”) statement defines the size of an array 
and allocates memory space for its elements. The expressions in pa- 
rentheses following the array name give the dimensions of the array. 
There may be from one to 88 dimensions (see Section 4.1.2, “Multi- 
dimensional Arrays’). 


Once an array has been defined ina D IM statement, any reference 
to that array with a different number of subscripts, or with a subscript 
that exceeds the maximum specified for that dimension in the DIM 
statement, will cause the program to halt with the message 


TBAD SUBSCRIPT ERROR 


Arrays are limited in size by the amount of available memory. See 
Section H.2, “Applesoft Memory Allocation,” for detailed information 
on the amount of space required by each type of array. 


Since array subscripts in Applesoft begin with © (not 1), there is actually 
one more than the specified number of subscripts in each dimension. 
For instance, the array T I TLE % defined in the second example above 
has 101 (not 100) elements. In the definition 

Dif (eS 


(les 2) 3) —array TEST has 13*4*6 = 


312 elements 


array TEST has 312 elements (13 times 4 times 6), not 180 (12 times 3 
times 5) as you might expect. 


When Applesoft encounters a reference to an array that has not yet 
been defined ina D IM statement, it automatically allocates space for 11 
subscripts (© to 1 0) in each dimension of the array. Later attempting to 
redefine the same array with a D IM statement will cause an error stop 
with the message 
TREDIM’D ARRAY ERROR 


Defining the same array in more than one D IM statement, or executing 
the same D IM statement twice, will produce the same message. 
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4.1.2 Multidimensional Arrays 


The examples shown in Figures 4-1 and 4-2 are both one-dimen- 
sional arrays. Actually, arrays in Applesoft may have as many as 88 
dimensions, subject to the amount of memory available. Arrays of 88 
dimensions aren't terribly useful, but those of two and three dimen- 
sions often are. 


Figure 4-3a shows an example of a two-dimensional array named 
EGGS, which has been defined by the D I M statement 


DIM EGGS (1+ 3) 





Figure 4-3a A two-dimensional array 


ArrayEGGS 
Column Column Column Column Column Column 
Q 1 2 3 | * 
Row? > |(0;0) (O48)1(044) 


Rowil — J (1390) C1ls3)] C154) 





For the newly perplexed, a metaphor may be helpful. Think of the 
array as an empty egg carton. On the outside is written the word 
EGGS§. When you open the egg carton, there are a dozen cup-like in- 
dentations where the eggs go—two rows of six cups each—corre- 
sponding to the elements of the array. Each of the cups is identified 

Don’t forget subscript 0! by arow number, ® or 1, andacolumn number from © to 3 (we're 
dealing with strange chickens here). 


Now suppose you place three eggs in the egg carton, in elements 
(O%+2),0¢0+3),and(1+3): 





LET EGGS (0+ #2) = EGG 
LET EGGS (0+ 3) = EGG 
LET EGGS (i+ 3) = EGG 
Figure 4-3b 
ArrayEGGS 


Column Column Column Column Column Column 
0 : 2 3 4 5 





Figure 4-3b shows the result. You might also elect to use your egg 
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Figure 4-3c 


Scrambled metaphor 


4.2 


string: a sequence of text characters 


String constants enclosed in double 
quotation marks 


Lowercase OK in string constants 


null string: a string containing no 
characters 


carton to hold small change. If you put a nickel in position (QO+1),a 
dime in position (1 +1), andadquarterin position (1 +4), 


LET EGGS (0, 1) = 83 

LET EGGS (i+ 1) = 10 

LET EGGS (i+ 4) = 25 
Array EGGS 


Column Column Column Column Column Column 
0 if 2 3 dj a 





your carton would look like Figure 4-3c. 


Actually, of course, you can’t store eggs in your Applesoft arrays, only 
numbers and strings—but after all, metaphors aren't always eggsact. 


Strings 


A string is asequence of text characters (letters, digits, and punctua- 
tion marks). Just as you can write numeric constants such as = 7 and 
< + <6 in your Applesoft programs, you can write string constants 
by enclosing the characters in the desired string between double 
quotation marks: 


"ON SALE FOR $49.95" 
"Truth 15 lmPervious to hissing" 
"HES504" 


Wom 


Even though Applesoft doesn't understand lowercase letters when you 
use them in keywords, it will allow you to use them in a string constant, 
as the second example above shows. 


A string can contain from 0 to 255 characters; when it contains no 
characters at all, itis called a null string. Two quotation marks with 
nothing between them denote the null string: 


—a String with no characters 


Strings 





String variable names end with $ 


String variables preset to null string 


4.2.1 


character code: a number used inside 
the computer to represent a text 
character 


ASCII: American Standard Code for In- 
formation Interchange; see Appendix C 


relational operators: see Section 2.3.2 
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A string variable can hold any string as its value. Its name must end 
with a dollar sign (#). Some legal string variable names are 


TITLES 
Ges 
DS 


Until they are given some other value with an assignment statement, 
all string variables are preset to the null string. 


Comparison of Strings: The ASCII Code 


The characters in a string are represented inside the computer in the 
form of numbers from & to i 2 7. The correspondence between 
these internal character codes and the characters they represent 

is based on a nationwide computer-industry standard called the 
American Standard Code for Information Interchange, or ASCII 
(pronounced “asky’). For instance, ASCII code &3 represents the 
uppercase letter A, 1 1 = represents a lowercase P, 32 represents 
the digit 4, 4:3 represents a plus sign (+), and so on. For acomplete 
table of ASCII character codes and the characters they represent, 
see Appendix C, “ASCII Character Codes.” 





Like numbers, strings can be compared with each other using the re- 
lational operators. The result of the comparison is based on the II 
codes of the characters in the strings. Applesoft looks for the first 
non-identical characters in the two strings and compares them by 
ASCII code to decide which is greater. For example, the character F 
(ASCII 7) is considered greater than the character D (ASCII G8) 
but less than the character H (ASCII 7 =). If one string is longer but 
begins with all the same characters as the other string, the longer 
string is considered greater. For example, 


nah is less than oe 
"AA" is less than "AB" 
"AB" is less than "BA" 
"Ap" is less than "ABC" 
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String comparisons can be used for con- 
ventional alphabetical order... 


... but watch out! 


WAL function: see Section 4.2.5 


LEN gives length of a string 


concatenation: see Section 4.2.3 


4.2.2 


Since letters of the alphabet are represented by consecutive codes in 
the ASCII table, comparisons between strings of alphabetic letters can 
be used to place the strings in conventional alphabetical order. For 


example, 

eo is less than 
"EO? is less than 
"EDGAR" is less than 
"EDWARD" is less than 
"EDWARD" is less than 


wee 


"EDGAR" 
"EDWARD " 
"EDWARDS" 
"FRANK " 


There are a few surprises, however: since uppercase letters precede 
lowercase letters in the ASCII chart, 


"Zenra” 


is less than 


"aardvark © 


And since strings are compared strictly character by character, 


ged = 


is less than 


dia ie 


If you want to compare two strings consisting of digits according to the 


numbers they represent, use the JAL function. 





The LEN Function 


The LEN (for “length”) function counts the number of characters ina 


string. The argument may be a string constant, a string variable, or a 
concatenation of two or more strings. For example, 


LEN ¢ 


LEN ¢ 


PRP PLE”) 


SAMPLES) 


—length of the string 
"APPLE"; yields 3 


—length of the string contained 
invariable SAMPLES 


LEN (A$ + "###" + BS) 
—length of the concatenation of 
variable A%, string "#**", 

and variable B $ 


Using LEN, you can assign the length of a string to a numeric vari- 
able and then use it in further operations: 


i090 LET NA = LEN (NY 


20 PR 


Strings 


HAWK. ") 
INT "THERE ARE 
IN THE STRING," 


HEART SOARS LIKE A 


3 


NA 


3 


CHARACTERS 








When executed, this program will display the following output on the 
screen: 


MMM THERE ARE 27 CHARACTERS IN THE STRING. 


4.2.3 


concatenate: to combine two or more 
strings into a single, longer string 


LEFT $ function: see Section 4.2.4 





If you concatenate two or more strings with a combined length of more 
than 255 (the maximum allowable string length), your program will halt 
with the message 

"STRING 100 LONG ERROR 

Instead of writing 

LEN AAS + 08 4° U9 


it’s safer to use 


Wen tee) + LEN Cees + Lea CC8y 





Concatenation of Strings 


Concatenation means “chaining together.” To concatenate two or 
more strings is to join them together into a new string containing all 
the characters of the original strings combined. This operation is rep- 
resented in Applesoft by a plus sign (+): 


"BORTS" + " AND "© + “NATASHA” 
—concatenation of the strings 
"BORTS"," AND "and 
"NATASHA"; yields the 
string "BORIS AND 
NATASHA" 


Fe + CS —concatenation of the contents 
of string variables F # andC$ 


H$# + "RATS!" —concatenation of the contents 
of string variable H $ with the 
string constant "RATS!" 


HS + LEFTS(Ces 4) —concatenation of the contents 
of string variable H $ with the 
leftmost four digits of the con- 
tents of string variable C 
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The program 


10 LET NAMES = "CHARLIE" 
—set victim’s name 

“0 LET TITLE = "DEAR "“ + NAME + ";," 
—form salutation 

30 PRINT TITLES —print salutation 

40 PRINT "HAVE WE GOT A SALE!" 


—print rest of message 


will display the output 





Result must not exceed 255 characters 


LEN function: see Section 4.2.2 


on the screen. The program 


10 LET AS = "GOOD ° —assign value to string variable 
20 LET A$ = AS + "GRIEF!" 
—extend string with 
concatenation 
30 PRINT Ag —display result 
will display 





If the result of a concatenation operation is a string more than 255 
characters in length, the program will halt with the error message 


TSTRING TOO LONG ERROR 


You can test how long the result of a concatenation will be before- 
hand by using the L_EN function. For example: 


19 LET AS = "HAPPY DAYS " 
20 LET Li = LEN (A%#) —howmanycharacters in A$? 
30 LET BS = “ARE HERE AGAIN" 
40 LET L2 = LEN (¢(B%) —howmanycharacters in B#% ? 
SO IF (Li + Le) 226 THEN LET At% = 

A$ + Bt —if the combined lengths of A$ 


and B $ are less than 256, 
combine the two strings into 
At 
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+ on strings doesn’t mean addition! 


WAL function: see Section 4.2.5 


4.2.4 


substring: a string that is part of another 
string 


LEFT $ extracts a substring from the 
beginning of a string 


Real arguments converted to integers 


a6 


Don’t confuse the concatenation of strings with the addition of numbers, 
even though both are represented in Applesoft by the same symbo! 
(+). The value of the expression 


be ot ae 
is the number 46; the value of the expression 
tt 1 2 it + ti 3] ie 


is the string 1234". lf you want to add two strings consisting of digits 
according to the numbers they represent, use the AL function. 





Substring Functions 


Applesoft has three built-in functions for extracting substrings froma 
string: 


@ LEFT extracts a substring from the beginning of a string. 
e ID extracts a substring from anywhere in a string. 


e kIGHT $ extracts a substring from the end of a string. 


The LEFT Function 


L.EF T $ extracts a specified number of characters from the begin- 
ning (left end) of astring. The LEF T $ function takes two arguments, 
separated by acomma: the string from which the characters are to be 
taken and the number of characters desired. For example, 


LEPTS ("THiS IS if!*» 4) 
—first 4 characters of the string 
"THIS I5 IT! "> yields 
“tHis” 


LEFT$S (NAMES, C + 2) —firstC + 2 charactersof 
the contents of string variable 
NAME $ 


If the value you give for the number of characters in the substring is a 
real number, LEF T % truncates it to the next lowest integer. If the 
value specified is greater than the length of the string, Applesoft re- 
turns the entire string; no extra characters are added. 


The number of characters requested must be between 1 and 235 or 
the program will halt with the message 


PILLEGAL QUANTITY ERROR 
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M 1D 4% extracts a substring from any- 
where ina string 


Third argument optional 





If you omit the dollar sign (#) from the function name LEF T $, Applesoft 
will treat L EF T as an arithmetic variable name, causing an error stop 
with the message 


TIYPE MISMATCH ERROR 


The MID% Function 


lM I D (for “middle”) extracts a specified number of characters from 
a specified position within a string. The M I D $ function takes three 
arguments, separated by commas: the string from which the charac- 
ters are to be taken, the position within the string of the first character, 
and the number of characters desired. For example, 


MIDS ("HOW DO T LOVE THEE?" +s 10% 4) 
—4 characters beginning at po- 
sition 10 in string "HOW DO 
IT LOVE THEE"; yields 
WErOWUE" 


MIDS (HOS, R + 7+ 2 * VY) 

—z * ‘J characters beginning 
atpositionk + /inthe 
contents of string variable 
Ho 


You may optionally leave out the third argument to MID. If you dont 
specify the number of characters you want, or if the number of char- 
acters you request is greater than the length of the string, MID 
yields all characters from the designated starting position to the end 
of the string: 


MIDS ("THERE THEY GO!":s 7) 
— all characters from position 7 
to endof string " THERE 
THEY GO! "; yields 
"THEY GO!" 


MIDS (As 10) — all characters from position 10 


to end of the contents of string 
variable A$ 


MIDS ("HI THERE" + 4+ 20) 
— all characters from position 
4toendofstring "HI 
THERE"; yields "THERE" 
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Real arguments converted to integers 


null string: a string containing no 
characters 


fk IGHT $ extracts a substring from 
the end ofa string 


Real arguments converted to integers 


If the value you give for the starting position or the number of charac- 
ters in the substring is a real number, “I D $ truncates it to the next 
lowest integer. If the designated starting point is greater than the 
length of the string, or if the number of characters requested is ®, 
MID yields the null string. 


The starting position must be between 1 and £33, and the number of 
characters between @ and 233, or the program will halt with the 
message 


TILLEGAL QUANTITY ERROR 


If you omit the dollar sign (#) from the function name M1 D4, Applesoft 
will treat M ID as an arithmetic variable name, causing an error stop with 
the message 


TIYPE MISMATCH ERROR 


The RIGHTS Function 


kX IT GHT % extracts a specified number of characters from the end 
(right end) of a string. The kk I GHT $ function takes two arguments, 
separated by acomma: the string from which the characters are to be 
taken and the number of characters desired. For example, 


RIGHTS ("GIMME A BREAK": 7) 
—last 7 characters of the string 
"GIMME A BREAK": 
yields "A BREAK" 


RIGHTS (NAME, C + 2) 
—lastC + 2&characters of 


the contents of string variable 
NAME 


lf the value you give for the number of characters in the substring is a 
real number, k I GHT $ truncates it to the next lowest integer. If the 
value specified is greater than the length of the string, Applesoft re- 
turns the entire string; no extra characters are added. 


The number of characters requested must be between i and 2535 or 
the program will halt with the message 


TILLEGAL QUANTITY ERROR 


If you omit the dollar sign (#) from the function name Fk I GHT #, Apple- 
soft will treat k IT GHT as an arithmetic variable name, causing an error 
stop with the message 


TLYPE MISMATCR ERRUR 
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4.2.5 


ASCil code: see Section 4.2.1 


5 Tk converts anumber to a string 


String Conversion Functions 


Strings and numbers are not the same, even when the string looks 
like anumber: 


2 # 129 —yields 246 
2 * "123" — TYPE MISMATCHerror 
LEFTS ("123",5 2) —yields "12" 
LEFT® (123, 2) —TYPE MISMATCHerror 


This section describes Applesoft’s built-in functions for converting 
between numeric and string values: 

@ STR% converts anumber to a corresponding string. 

@ 'JAL converts a string to a corresponding number. 

@ CHI converts an ASCII code to the corresponding character. 


@ ASC converts acharacter to the corresponding ASCII code. 


The STR Function 


The STIX % (for “string”) function converts a numeric value into a 
string representing that value. For example, 


STRS (€-100) —astring representing the num- 
ber -100;yields °-i100" 


SIRS (gsidisdi — astring representing the num- 
ber 3.14139; yields 
"se Lolog” 


STR (CMARK ) —a string representing the nu- 
meric value of real variable 
MARK 


STRS (COUNTS) — astring representing the nu- 
meric value of integer variable 
COUNT 


STR (B°2 - G#A#C) — a string representing the nu- 
meric value of the expression 
B°e - G#A#C 
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JAL converts a string to a number 


ly I GHT $ function: see Section 4.2.4 





The string produced by 57 $ is in the same format that Applesoft 
uses to display or print numbers; see Appendix |, “Display Formats 
for Numbers,’ for details. For example, 


STR (100 000 000) —yields "100000000" 
STRS €1 000 000 000) — yields "1E+09" 
STR (-.03) —yields *-.,03°" 

STR (-.,003) —yields "-3E-03" 


if the numeric value of the argument falls outside the allowable 
range for realnumbers (-9+.99999999E + 37 to 
+3,.99999999E + 37), the program will halt with the message 


FTOVERFLOW ERROR 


The AL Function 


The VAL (for “value”) function converts a string to the numeric value 
it represents. For example, 


VAL ("4096") — number represented by the 
string "4056"; yields 4096 
VAL ("-1,303E4+2") — number represented by the 


string “»14S503E+2": 
yields -130.5 
VAL (WHOLES + "," + FRACS) 
— number represented by the 


concatenation of strings 
WHOLES, ".",andFRACS 


VAL € RIGHT (QO, 4) 3 
— number represented by the 
last 4 characters of string 9 $ 
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JAL recognizes same number formats 
as INPUT; see Section 5.1.2 


CHR converts an ASCII code to the 
corresponding character 


ASCII code: see Section 4.2.1 and 
Appendix C 


Real arguments converted to integers 


(JAL recognizes the same number formats that can be used in key- 
board input; see “Rules for Numeric Input” in Section 5.1.2, “The 
INPUT Statement.” If AL encounters a non-numeric character in 
its argument string, it yields the numeric value of everything up to the 
first non-numeric character, ignoring the rest of the string. (The digits 
© through §, the signs + and -, the decimal point (+ ), and the letter 
E for scientific notation are considered numeric characters. Spaces 
are also allowed, and are simply ignored.) If the first character in the 
string is non-numeric, J AL yields a value of ©. For example, 


VAL ("12.584 OR SO") —yields 12.34 
VAL C"™ABOUT 4,37") — yields © 
If the absolute value of '!AL.’s result is greater than 1 E38 or contains 


more than 38 digits (including trailing zeros), the program will halt with 
the message 


TOVERFLOW ERROR 


The CHR Function 


The CHR # (for “character’) function regards its single numeric ar- 
gument as an ASCII character code and yields a one-character 
string consisting of the corresponding character. For example, 


CHR (68) — character with ASCII code 
G8; yields the string *D" 

CHR (47) —character with ASCII code 4 7: 
yields the string ° / " 

CHRE (7) —character with ASCII code 7; 


yields a string containing 
the ASCII bell character 


(CONTROL |-C) 


CHR (Ci) —character whose ASCII code 
is the value of variable C i 

CHR (L% + G4) —character whose ASCII code 
is the value of expression 
L% + 64 


If the value of the argument is a real number, CHR $ truncates it to the 
next lowest integer. For example, 


CHRS (81.9) —argument truncated to 81; 
yields "Q" 


Strings 





ASC converts a character to the 
corresponding ASCII code 


ASCII code: see Section 4.2.1 and 
Appendix C 


M 1D function: see Section 4.2.4 


null string: a string containing no 
characters 








An argument less than © or greater than 235 will cause the program to 
halt with the message 


TILLEGAL QUANTITY ERROR 


The ASC Function 


The ASC (for “ASCII”) function takes a single string argument and 
yields the ASCII code corresponding to the first character in the 


string. For example, 


ASC ("D") 


ASC ("/") 


ASC ("e. @. Cummings" 


ASC (BO) 


ASC ( MIDS (NAMES > 


ae, 


—ASCII code for character DB; 
yields 68 


—ASCII code for character /; 
yields 47 


) 
—ASCII code for character ¢: 
yields 101 


—ASCIlI code for the first charac- 
terin string Bas 


) 
—ASCIlI code for the fifth charac- 
terin string NAME $ 


If the argument given to ASC is the null string, the program will halt with 


the message 


PILLEGAL QUANTITY ERROR 


Arrays and Strings 





Input/Output 





95 5.1 


96 
97 
98 
99 
100 
102 
104 
105 
108 
109 
109 
110 
111 
111 
113 
117 
119 
119 
119 
120 
121 
122 
124 
125 
126 
127 
128 
128 
129 
129 
130 
131 
131 
131 


Input/Output 


5.2 


Input 
5.1.1 The IN# Statement 
5.1.2 The INPUT Statement 
Multiple Inputs on the Same Line 
Rules for String Input 
Rules for Numeric Input 
An “Input Anything” Routine 
5.1.3 The GET Statement 
5.1.4 The READ and DATA Statements 
5.1.5 TheRESTORE Statement 
5.1.6 Miscellaneous Input Facilities 
The Hand Controls 
Cassette Input 
Output 
5.2.1 The PR# Statement 
5.22 The PRINT Statement 
5.2.3 Number Formats 
5.2.4 Formatting Text on the Screen 
The TEXT Statement 
The HOME Statement 
The SPC Function 
The TAB Function 
The HT AB Statement 
The ¥ TAB Statement 
The PQS Function 
The INVERSE Statement 
The FLASH Statement 
The NORMAL Statement 
The SPEED = Statement 
The Text Window 
5.2.5 Miscellaneous Output Facilities 
Controlling the Speaker 
Annunciator Output 
The Utility Strobe 
Cassette Output 



































input: see Section 5.1 


output: see Section 5.2 


5.1 


input: the transfer of information into the 
computer from an external source 


* 


I N# statement: see Section 5.1.1 


INPUT statement: see Section 5.1.2 


GET statement: see Section 5.1.3 


READ statement: see Section 5.1.4 
DATA statement: see Section 5.1.4 


RESTORE statement: see Section 
5.1.5 


miscellaneous input: see Section 5.1.6 






Chapter5 — 


Input/Output 


This chapter is concerned with the ways in which Applesoft programs 
communicate with the outside world. Here are described Applesoft’s 
facilities for getting information into and out of the computer and for 
controlling the way information is presented. 


Section 5.1, “Input,” deals with the various statements through which 
Applesoft programs receive information for processing. 


Section 5.2, “Output,” describes how programs transfer information 
to the “outside world”: to the display screen, printers, and so forth. 


Input 


The input statements discussed in this section enable Applesoft pro- 
grams to receive information for processing, either from the keyboard 
or from a peripheral device connected to the computer via one of the 
expansion slots: 


e The IN# statement controls the source from which the com- 
puter receives its input. 


@ The INPUT statement accepts a line of input from the current 
input device. 


@ The GET statement reads a single character from the current in- 
put device. 


e TheREAD, DATA, andRESTORE statements are used to read 
information from within the running program itself. 


@ A few miscellaneous input facilities are available for reading the 
hand controls and for reading information from a cassette tape 
recorder. 
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5.1.1 


I N# specifies source for subsequent 
input 


expansion slot: see Apple //e Owner's 
Manual and Apple Ile Reference Manual 


Slot number © specifies input from 
keyboard 


GET statement: see Section 5.1.3 


PR # statement: see Section 5.2.1 


Be careful! 


CONTROL /-| RESET|:see Section 1.3.2 





The 1N# Statement 
IN# 2 
IN# X 
IN# SLOT - J 


The IN# statement specifies the source from which the computer 
will receive subsequent input. The expression following the keyword 
I N# should evaluate to anumber between @ and 7, designating the 
expansion slot from which input is to be taken. 


When Applesoft is started up, it is set to receive input from the 
keyboard. Executing an I N# statement with a slot number from i 
to 7 instructs Applesoft to receive input instead from the peripheral 
input device (such as a terminal or modem) connected to the 
designated slot. A slot number of ® reestablishes the keyboard as 
the current input device. For example, the following program 
fragment reads a single character from the device connected to 
slot 2, then reestablishes keyboard input: 


S10 IN# 2 —accept input from device in 
slot 2 

220 GET AS —read one character from 
device in slot 2 

230 INF 0 —accept future input from 
keyboard 


Notice that the character # is part of the keyword I N# and cannot 
be omitted. 


Restarting the System with I N#: If the slot designated in an IN# or 
P lk # statement contains a disk controller card, Applesoft will atternpt to 
restart (often called “booting”) the system from the disk contained in 
drive 1 connected to that slot. When you do this on purpose, it’s the 
usual way of restarting the system from within Applesoft; when you do it 
by mistake, it can be a catastrophe. 


Warning 
If no input device is connected to the slot designated in an I N# state- 


ment, the system will hang. To recover, use { CONTROL J-[ RESET |, 


A slot number between 8 and £35 will cause unpredictable and possi- 
bly aberrant behavior. 
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INPU Treads aline of input 


current input device: see Section 5.1.1 


prompt: to remind or signal the user that 
some action is expected 


current output device: see Section 
5.2.1 


Prompting message optional 





A slot number less than © or greater than 233 will stop the program 
with the message 


VILLEGAL QUANTITY ERROR 





The INPUT Statement 
INPUT PRICE 


INPUT MNTHA+s DAYAZ+s YEARZ 

INPUT "WHAT IS YOUR PASSWORD? ©; 
PASSWD$ 

INPUT "3 & 


The INPUT statement accepts a line of input (terminated by 

[ RETURN |) from the current input device, containing values to be as- 
signed to one or more variables. The variables to be read are listed in 
the INPUT statement, separated by commas. 


The INPUT statement may optionally include a message to be dis- 
played or printed on the current output device, prompting the user for 
the desired input. If present, the prompting message must be given 
as a string constant immediately following the keyword INPUT and 
followed by a semicolon to separate it from the list of variable names. 
The specified prompting string is reproduced exactly as written; if 
displayed on the screen, it is immediately followed on the same line 
by the cursor. If the prompting message is omitted from the INPUT 
statement, a question mark (‘") is used; the question mark can be 
suppressed by supplying a null string as the prompting message. For 
example, 
10 PRINT "WHAT IS YOUR AGE+ PLEASE?" 
—display prompting message on 
its own line 
—prompt with * and wait for 
response 
STREET NAME?T "3 ST4 
—display prompting message on 
same line as cursor and wait 
for response 
YOUR FIRST AND 
SEPARATED BY A COMMA: " 
—display prompting message on 
its own line 
L.N%—suppress ? and wait for two 
responses separated by a 
comma 


“0 INPUT AGE 


INPUT ® YOUR 


40 PRINT “PLEASE TYPE 


LAST NAMES » 


INPUT 5 FN + 


Input 





Colon causes remainder of line to be 
ignored 


[ CONTROL |-C: see Section 1.3.2 


Length of input line limited 


No INPUT in immediate execution 
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The INPUT statement in line = above displays a question mark to 
prompt the user for input, followed by the cursor. The INPUT state- 
ment in line 30 displays the prompting message YOUR STREET 
NAME T instead of the question mark, again followed by the cursor. 
The INPUT statement in line 3 displays the cursor only, with no 
question mark and no prompting message of any kind. 


lf the user types a colon (: ) as part of an input line, the remainder of that 
input line is ignored. The ASCII null character ({ contrac |-C) has the 
same effect. 


An INPUT statement can be interrupted by [ controt |-C, but only if it 
is the first character typed on an input line. The program halts when the 


key is pressed at the end of that line. A -C that is 


not the first character of the input line is treated as part of the input, the 
same as any other character. 


Be sure to give your users clear instructions about how long their re- 
sponses can be. If the user types an input line longer than 255 charac- 
ters, the whole line will be canceled and will have to be retyped from the 
beginning (the Apple Ile’s speaker will beep from about the 245th char- 
acter, but no message will be displayed). A response of more than 239 
but fewer than 255 characters will be truncated to 239 characters with no 
warning message displayed. 


The INPUT statement can be executed only from within a program; 
you can't use this statement in immediate execution. 


Multiple Inputs on the Same Line 


The INPUT statement may list any number of variables to be read 
from the same input line. The user’s responses to these variables 
must be separated by commas. You can mix string and numeric vari- 
ables inthe same INPUT statement, but the user's responses must 
each be of the correct type. 


lf the user presses the[ RETURN |key (or types a colon or (CONTROL]-E) 


without typing enough responses for all the variables listed in the 
INPUT statement, Applesoft displays two question marks to show 
that it expects a further response. If acolon, comma, or [cONTROL]-@ 
is the first character of a response, Applesoft interprets the response 
as zero or as the null string (depending on the type of variable speci- 
fied) and the program continues with the next statement. 
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Be kind to your users! 


Quotation marks optional 


Leading spaces ignored 


Rules for quoted responses 





lf the user types more responses than Applesoft expects, or types a 
colon into the final expected response, Applesoft displays the 
message 


FEXTRA IGNORED 


and program execution continues. If the last response is shortened 


by a{ CONTROL |-€—the program continues but no message is 
displayed. 


Programming Tip: Multiple inputs on the same line can be confusing 
for your users; it’s best not to use them except for “quick and dirty” test- 
ing purposes while you’re debugging your code. Instead of asking for 
something terribly unfriendly like 


PLEASE I[YPE LAS! NAME: FIRST NAME, MIDDLE 
INITIAL: 


use aform such as 
PLEASE TYPE YOUR FIRST NAME: 
followed by 


PLEASE TYPE YOUR MIDDLE INITIAL: 
JUST PRESS RETURN IF YOU HAVE NONE 


and soon. You'll be able to give much clearer instructions, your user will 
have an easier time giving you what you want, and you'll be better able to 
detect and deal with errors in the input. 


Rules for String Input 


The following rules govern the responses the user types to string 
variables inthe INPUT statement: 


@ The user's response to a string variable may be typed with or 
without enclosing quotation marks. 


@ Applesoft ignores all spaces preceding the first nonspace 
character. 


@  |fthe first nonspace character is a quotation mark, the input 
string is considered to include everything up to (but not including) 
the next quotation mark, [ CONTROL |-@, or [ RETURN }. The string 
may include commas and colons, but may not include quotation 
marks, since these would be interpreted as marking the end of 
the string. Spaces following the closing quotation mark are ig- 
nored, but any other character causes the response to be re- 
jected with the message 


TREENTER 


Input 





Rules for unquoted responses 


Null responses OK 


Control characters cause problems 


String expressions don't work 


All spaces ignored 








@ Ifthe first nonspace character is not a quotation mark, the input 
string includes everything up to (but not including) the next 
comma, colon, [ CONTROL |-@, or [ RETURN ]. The string may in- 
clude quotation marks, but may not include commas or colons, 
since these would be interpreted as marking the end of the string. 
Spaces following the last nonspace character are accepted as 
part of the input string. 


e@ lf the first nonspace character is acomma, colon, | CONTROL |-&, 
Or | RETURN |, the response is interpreted as the null string and 
program execution continues. 


e@ The following control characters cannot be included in the 


response: 
@® [| CONTROL |-H (equivalent to the[ LEFT-arROW | or backspace 
key) 


@® ({conTRoL |-M (equivalent to the key) 


@® | CONTROL |-A& (cancels the input line) 


@® [controt |-@ (ASCII null character; causes remainder of in- 
put line to be ignored) 


In general, control characters cause problems and should not be 
used in responding to INPUT statements. 


@ The response to a string variable must be a single string or a con- 
stant; it cannot be a string expression involving concatenation, 
LEFT, MID%, RIGHT &, orother string operations. Re- 
sponses such as 


A$ + BS 
LEFTS (MNTHS:, 3) 
RIGHTS (NAMES, L - (FL + 2)) 


will be accepted exactly as typed, character for character (up to 
the first comma), and will not be evaluated as string expressions. 


Rules for Numeric Input 

Listed below are the rules governing the user’s responses to numeric 
variables. If a response is typed that doesn’t conform to these rules, 
Applesoft will display the message 

TREENTER 


reissue the prompting message, and wait for another response. 


@ Spaces are ignored in any position. 
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@ The response is considered to include all nonspace characters 
up to (but not including) the next comma, colon, [ CONTROL |-&, or 


RETURN |. 
@ The response may include numeric characters and spaces only. 
Numeric characters only Numeric characters include the digits ® to 3, the signs + and -, 


the period (decimal point), and the letter E for scientific notation. 
A response containing a non-numeric character in any position is 
invalid. 


scientific notation: see Section |.2 


@ Numeric responses consist of the following elements. Any or all 
of these elements may be omitted, except that the sign or value 
Form of numbers of the exponent may not appear unless preceded by the letter E. 
Those that are included must be given in the order listed: 


Asign(+ or —) 
One or more digits 
A decimal point (: ) 


One or more digits 


The letter E for scientific notation 
@ Asign(-+ or —) forthe exponent 
@ Oneor more digits 


Degenerate cases interpreted as © Even forms suchas + E- and «E are accepted, and are inter- 
preted as 0. 


e If the first nonspace character is acomma, colon, or [ RETURN ], 
Null responses interpreted as © the response is interpreted as ® and program execution contin- 


ues. Aresponse beginning with { CONTROL J-& is invalid. 
@ The following control characters have special meanings: 


@ {conTROL |-H (equivalent to the [ LEFT-ARROW |or backspace 
key) 


@ (CONTROL |-M (equivalent to the key) 
8 -% (cancels the input line) 


@ (conTroc |-@ (ASCII null character; causes remainder of in- 
put line to be ignored) 


Most control characters illegal A response containing any other control character, in any posi- 
tion, is invalid. 


Arithmetic expressions invalid @ The response to a numeric variable must be a single number; it 
cannot be a numeric expression involving arithmetic operations 
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WAL function: see Section 4.2.5 


POKE statement: see Section 7.1.2 








or function calls. Responses such as 


if2 
B°S - GAC 
SQR (2) 


are invalid because of the non-numeric characters. 


It’s a good idea to use string variables to accept all numeric inputs, using 
the VAL function to convert them to numeric values. This makes it eas- 
ier to detect and deal with user errors and to display alternate prompting 
messages. 


An “Input Anything” Routine 


The INPUT statement interprets the colon and the comma (and 
sometimes the quotation mark) as special symbols and rejects any- 
thing typed after them in the input line. Here’s a bit of magic you can 
use if you anticipate that your user's response may include any of 
these characters. 


The following Applesoft subroutine uses the POKE statement to 
store a special machine-language routine into the computer's mem- 
ory, one byte at atime, beginning at address 768. The machine-lan- 
guage routine will accept all characters in the input, including colons, 
commas, and quotation marks, without “censoring” them, and will 
assign them, character by character, to a string variable for further 
processing. (The line numbers used below are arbitrary; you can 
locate this subroutine anywhere you like in your program.) 


G2000 REM SET UP "INPUT ANYTHING" 
ROUTINE 
62010 LET IN = "xX" —IN# mustbe first variable 


created 
G2020 FOR J = 768 TO 790 
—these are memory addresses 
where machine language is to 
be stored 
—get a byte of machine 
language 
G2O040 POKE J+ I —store it at next location 
S2050 NEAT — go back for next byte 
G2060 DATA 1Ge:+ O+ Bes Liv+s 2533+ 160, 24 
19UG+ 143%, 105, 200+ i168» O», 1a3, 
103+ £00, 169+ 2+ 145+ 105+ 76+ 
ofr £13 —these are the actual bytes of 
machine language 
—return to statement following 
point of call 


G2030 READ I 


62070 RETURN 
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CALL statement: see Section 7.1.3 





The DATA statement containing the machine language must be re- 
produced in your program exactly as shown. 


The following subroutine uses the CALL statement to call the ma- 
chine-language routine at address 768. (Again, this subroutine can 
be located anywhere in your Applesoft program, not necessarily at 
line number 63000.) 


G3000 REM CALL "INPUT ANYTHING" ROUTINE 
G3010 CALL 768 —call machine-language routine 
G30f0 INS = MIDS CINSs 13 
— IN#% now holds the input that 
the machine-language routine 
accepted 
G3030 RETURN —return to statement following 
point of call 


To accept a line of input from the user, instead of using a statement 
such as 


igo INPUT S# 
substitute this line: 
100 GUSBUB &3000 2+ LET S& = inst 


The variable 5 # now contains whatever input the user typed, includ- 
ing the “forbidden” characters; your program can proceed to process 
the input in whatever way is appropriate. 


For technical reasons having to do with the way variables are stored in 
memory, the string variable used to pass the user’s response between 
machine language and Applesoft (arbitrarily called I N% in the example 
above) must be the first variable used or defined in the program. To be 
safe, you might want to call the “input anything” setup routine from line 
number ©: 


O GOSUB 62000 








GET reads a single input character 


current input device: see Section 5.1.1 


semicolon: see Section 5.2.2 


No GET in immediate execution 


[ CONTROL ]-C won'tinterrupt a GET 
[ CONTROL |-C: see Section 1.3.2 





The GET Statement 


Get L& 
GET S#(N) 
GET Ci¢, C2$, C34 


The GET statement reads a single character from the current input 
device. Although it can be used to read from any peripheral input de- 
vice (such as a terminal or modem), it is seldom used in actual prac- 
tice with anything other than the keyboard. 


GET accepts one character from the current input device for each of 
the string variables listed following the Keyword GET. Each single 
character is read as soon as it is typed, without waiting for the user to 
press the key. The character is not displayed on the 
screen, and the cursor is not moved in any way. 


Here’s an example of a program fragment using GET: 


310 PRINT "PRESS THE “Y¥’ KEY TO GO ON: "s 
—prompt user for response 
(Semicolon keeps cursor on 
same line) 
320 GET AS —wait for user to press key 
330 IF AS «se "¥" THEN 320 
—keep cycling until user presses 
correct key 
340 PRINT —move cursor to new line (can- 
cels effect of semicolon from 
line 310) 
390 PRINT "THANK ‘OU " —politeness from machines is 
always welcome 


The GET statement can be executed only from within a program; you 
cant use this statement in immediate execution. 


If typed in response toa GET, -C is treated like any other 
character; it does not interrupt program execution. 
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DOS: Disk Operating System 


WAL function: see Section 4.2.5 


5.1.4 


EAD reads information from body of 
program 


DATA sets up information for use by 
READ 


A DOS command issued immediately after a GET will not be recog- 
nized. For DOS commands to be executed properly, you must issue a 
character immediately after the GE T and before the DOS 
command. An easy way to do this is with an empty PR INT statement: 


PRINT 


See your DOS manual for more information. 


Numeric Inputs with GE T: The GET statement is neither designed nor 
intended to obtain values for numeric variables. You may attempt to do 
so at your own peril, subject to the following limitations: 


@ Acommaoracolon will result in the message 
TEXTRA IGNORED 


and will be interpreted as a numeric value of ©. 


e Aplus sign, minus sign, [ contrat |-@, E, space, or period will be 
interpreted as a numeric value of 0. 


e@ Any non-numeric character will cause the program to halt with a 
syntax error. 


It’s better to use only string variables with the GE T statement, using the 
JAL function to convert the response to a numeric value. 





The READ and DATA Statements 


READ PRICE 

READ A+ Be MACT) + JA+ S#0C2¥5 - Lis TS 
DATA 12.9+ HI HO; i168 

DATA 2.236 


The READ and DATA statements are used to read information from 
within the body of the Applesoft program itself, rather than from the 
keyboard or an input device. There may be any number of DATA 
statements in a program, each containing a list of one or more items 
of information (numbers or strings) following the keyword DATA and 
separated by commas. All of the DATA statements in the program 
are considered to form one long list of items, in sequential order of 
line numbers; each READ statement reads one or more items from 
this list. 
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RESTORE statement: see Section 
5.1.5 


Don't read past end of list! 


Rules for numeric and string input: 


see Section 5.1.2 


DATA statements may appear 
anywhere 
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Each time it executes a READ statement, Applesoft remembers the 
last item read from the DATA list. The next RE AD always begins 
with the next item in the list. There is no way to “back up” or ‘skip for- 
ward” inthe DATA list, but you can start over from the beginning of 
the list with the RES TORE statement. 


An attempt to read past the end of the DAT A list will halt the program 
with a message such as 


TOUT OF. DATA. ERROR. IN 1a65 


identifying the line number of the Fk EAD statement in which the error oc- 
curred. Leaving part of the DATA list unread at the end of the program 
does not cause an error. 


The items ina DATA statement are separated by commas and follow 
the usual rules for numeric and string input, except thata DATA 
statement cannot contain a colon (:). The number of items in each 
DATA statement is limited only by the length of the program line. A 
DATA statement may appear anywhere in your program; it need not 
precede the READ statement that uses it. There is no limit to the 
number of DATA statements in a program. 


Here's an example program showing the use of the READ and 
DATA statements: 


10 DATA "GO WEST+ YOUNG MAN" 
—item containing a comma; OK 
between quotation marks 
20 DATA 3.14159; 2% "SAM" 
—mixed types insame DATA 
statement 
30 READ AG: B —readGO WEST:+ YOUNG 
MAN into string variable A$ 
and 3+ 141359 into real vari- 
able 6; notice that these items 
come from two different 
DATA statements 
40 READ Cé+ D+ ES —read = into integer variable C %,, 
3AM into string variable D , 
and THE "WORLD" [5 
FLAT into string variable E #; 
begins with next item following 
previous RE AD statement 
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Null items interpreted as 0 or null string 


WAL function: see Section 4.2.5 


Most control characters treated as 
ordinary characters 


[ CONTROL J-C: see Section 1.3.2 





SO DATA THE "WORLD" IS FLAT 

—item containing quotation 
marks; notice that this item fol- 
lows the READ statement that 


uses it 

60 PRINT ES —display THE "WORLD" 
15 FLAT 

70 PRINT AS —display GO WEST > 
YOUNG MAN 


80 DATA 38.6+ 37+ —-273.16 


—these items never read 


90 END 


Null items ina DATA statement are interpreted as © or the null 
string, depending on the type of variable to which they are assigned 
ina READ statement. A null item is read whenever there are no non- 


Space characters 

@ between the keyword DATA and the end of the program line 
@ between the keyword DATA and the first comma 

@ between two consecutive commas 

@ between the last comma and the end of the program line 
Thus the statement 

DATA++ 


contains three null items. 


Input 


An attempt to read a string value ina DATA statement with a numeric 
variable ina READ statement causes a syntax error. Numeric values 
can be read into string variables, but must be evaluated with the VAL 
function before they can be used as numbers. 


The characters [ContRoL |-H, [ controt |-M, { controt |-%, and 
-@ cannot be embedded in a DATA statement. Any other 


control character typed into a DAT A statement is treated as an 
ordinary character and becomes part of the input. A{ contrat |-C 
character ina DATA statement will not interrupt the program. 


The READ statement can be executed only from within a program; you 
can’t use this statement in immediate execution. 





RESTORE restarts DATA list 








515 The RESTORE Statement 
RESTORE 


The RESTORE statement restarts the DATA list from the beginning. 
After RESTORE is executed, the next READ statement will read the 
first item in the first DA T A statement in the program. For example, 


10 
20 


30 


4o 


50 
60 


4] 
BO 


QO 


LUO 


110 
120 


DATA "GO 


DATA 3.141395 2, 


READ AG: 


READ Ch? 


DATA THE 
PRINT ES 


RESTORE 
READ Q¢ 


PRINT Q¢ 


PRINT AS 


END 


WEST + YOUNG MAN" 


B 


DS, ES 


"WORLD" 


+ Sanh i 

—readGO WEST; ‘YOQUNG 
MAN into string variable A& 
and 3+ 14139 into real vari- 
able B 

—read = into integer variable C 4%, 
3AM into string variable D$, 
and THE "WORLD" [5 
FLAT into string variable E $ 

IS FLAT 

—display THE "WORLD" 
IS FLAT 

—restart list from beginning 

—readGO WEST+ YOUNG 
MAN into string variable 9 

—display GO WEST + 
YOUNG MAN 

—displayGOQ WEST + 
YOUNG MAN (value of AS 
still intact) 


DATA 98.G+ 37+ -—273.16 


—these items never read 


There is no easy way to reposition the DAT 4 list to a specific desired 
item or line number. The only other Applesoft statement that affects 
the positioning of the DATA list is RK UN, which also restarts the list 
from the beginning. 
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PDL reads dials on hand controls 


Standard hand controls numbered © 
and i 


Result of PDL is between 0 and 255 


Miscellaneous Input Facilities 


This section covers Applesoft's facilities for dealing with the remain- 
ing input features of the Apple Ile: the hand controls and cassette 
tape input. 


The Hand Controls 


If you have a set of hand controls connected to your computer, you 
can use the PDL function to read their dial settings. The Apple lle 
can accommodate as many as four hand controls, numbered 0 to 3, 
connected through the 9-pin hand control connector on the comput- 
er’s back panel or the GAME |/O connector inside the case on the 
main logic board. However, the standard Apple hand control set con- 
sists of only two controls, numbered 0 and 1. 


The PDL function takes one argument, the number of the hand con- 
trol to be read, and yields an integer from © to 233 representing the 
current position of the dial on that control. For example, 


10 LET K = PDL (0) —readhandcontrol0 
£09 LET PZ = x * 40 / 25671 
—reduce to anumber from i to 
Ao 
30 HTAB P4&% —move cursor to indicated posi- 
tion on current line 
40 PRINT "<" —display the character < 
20 LET ¥Y = PDL ¢1)  —readhandcontrol 1 
GO LET O4 = Y¥ * 40 / 25641 
—reduce to anumber from i to 
ao 
7O HTAB Q% —move cursor to indicated posi- 
tion on current line 
80 PRINT ">" —display the character > 
90 IF XK = 0 AND ¥Y = 0 THEN END 
—end program when both hand 
controls read 
100 GOTO 10 —otherwise repeat the process 


If the argument given to PDL is less than © or greater than 235, the 
program will halt with the message 
PILLEGAL QUANTITY ERROR 


If the argument is between 4 and 235, orifno hand control of the desig- 
nated number is connected, the results are unpredictable. 
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Allow a delay between calls to PDL 


Reading the hand control buttons 


PEEK function: see Section 7.1.1 


For more information... 


LOAD command: see Section 1.2.6 and 
Appendix M 


RECALL statement: see Appendix M 


SHLOAD statement: see Section 6.3.2 
and Appendix M 








lf your program reads two hand controls in consecutive statements, the 
reading from the first hand control may affect the reading from the sec- 
ond. To obtain more accurate readings, allow several program lines be- 
tween calls to PDL. or use a short delay loop such as 


PORK =. de PO Ae POs A 


between PDL calls. 


Historical Note: The function name PDL. stands for “paddle,” which in 
turn is short for “game paddle,” an older name for the Apple lle’s hand 
controls. 


The buttons on the hand controls can be read with the function calls 


PEEK (-16287) —yields avalue > i 2? if button 
on hand control 0 is being 
pressed, <= i127 ifnot 


PEEK (-16286) —yields avalue > 127 if button 
on hand control 1 is being 
pressed, <= 12/7 ifnot 


PEEK (-16283) —yields avalue > i 2 / if button 
on hand control 2 is being 
pressed, <= iz? ifnot 


There is no way to read the button on hand control 3. The PEEK calls 
listed above are also used to read the “apple keys” on the Apple Ile 
keyboard: the key is equivalent to the button on hand 
control O, and | SOLID-APPLE | is equivalent to the button on hand 
control 1. 


See the Apple Ile Reference Manual for detailed technical information 
on the 9-pin hand control connector and the internal GAME I/O 
connector. 


Cassette Input 


Three Applesoft statements, LOAD, RECALL, and SHLOAD, can 
be used to read information from a cassette tape recorder. L. OAD 
reads an Applesoft program into memory from tape; RECALL reads 
the contents of an integer or real array; SHL.OAD reads a shape ta- 
ble for use in high-resolution graphics. For details, see Appendix M, 
“If You Have a Cassette Recorder.” 
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5.2 
output: the transfer of information from 
the computer to an external destination 


Pl¥# statement: see Section 5.2.1 


Pik INT statement: see Section 5.2.2 


number formats: see Section 5.2.3 


screen formatting: see Section 5.2.4 


miscellaneous output: see Section 
5.2.5 


5.2.1 


Pl # specifies destination for subse- 
quent output 


expansion slot: see Apple /le Owner's 
Manual and Apple Ile Reference Manual 


Slot number © specifies output to the 
screen 


Output 


This section describes the output facilities available in Applesoft: 


@ Section 5.2.1 covers the PF’ # statement, which controls the des- 
tination to which output is directed. 


@ Section 5.2.2 contains a detailed discussion of the PR INT 
statement, Applesoft’s primary output statement. 


@® Section 5.2.3 gives details on the way numbers are formatted 
when written with the PR INT statement. 


@ Section 5.2.4 describes Applesoft’s wide variety of facilities for 
controlling the format in which textual information is displayed on 
the screen. 


@® Section 5.2.5 touches briefly on various miscellaneous output fa- 
cilities not covered elsewhere: the Apple lle’s built-in speaker, 
annunciator outputs, utility strobe, and cassette tape output. 





The PR# Statement 


PR# 1 
PRA x 
PR# SLOT - J 


The PR # statement specifies the destination to which the computer 
will send subsequent output. The expression following the keyword 
P lk # should evaluate to a number between © and 7, designating the 
expansion slot to which output is to be sent. 


When Applesoft is started up, it is set to send output to the display 
screen. Executing a PX # statement with a slot number from i to 7 
instructs Applesoft to send output instead to the peripheral output de- 
vice (such as a printer, terminal, or modem) connected to the desig- 
nated slot. A slot number of ® reestablishes the display screen as the 
current output device. For example, the following program fragment 
writes a string of characters to the device connected to slot 1, then re- 
establishes screen output: 


Gio PR# 1 —send output to device in slot 1 

G20 PRINT 2$ —write contents of string vari- 
able 2 # to device in slot 1 

G30 PR# 0 —send future output to screen 


Notice that the character # is part of the keyword Pk # and cannot 
be omitted. 
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I N# statement: see Section 5.1.1 


Be careful! 


CONTROL |-] RESET |: see Section 1.3.2 


A 


Restarting the System with PR #: If the slot designated inan I N# or 
Pk # statement contains a disk controller card, Applesoft will attempt to 
restart (often called “booting”) the system from the disk contained in 
drive 1 connected to that slot. When you do this on purpose, it’s the 
usual way of restarting the system from within Applesoft; when you do it 
by mistake, it can be a catastrophe. 


Warning 
If no output device is connected to the slot designated in a PF # state- 


ment, the system will hang. To recover, use [ CONTROL |- 


A slot number between 8 and 233 will cause unpredictable and possi- 
bly aberrant behavior. 


Warning 


lf you are using the Apple Ile 80-Column Text Card, always be sure to 
deactivate it by typing [ Esc |{ conTRoL |-9 before using PR # to transfer 
output to another slot. Leaving the Text Card active while using a printer 
or while restarting the system from a disk may produce amusing but 
confusing fireworks on the screen. 


Although the Text Card is installed in the Apple Ile’s special auxiliary 
slot, it appears to the computer as if it were in slot 3. So to reactivate the 
Text Card after sending output to another device, type 


PR# 3 


You can also return output to the 40-column screen with the Text Card 
inactive by typing 


PR# 0 


However, don’'tuse PR# © to redirect output directly from the Text 
Card to the 40-column screen without first deactivating the Text Card 
with -). Under certain circumstances, this may cause 
text intended for the screen to be written outside the area of memory 
reserved for it, possibly destroying your Applesoft program or other 
important information. 


A slot number less than © or greater than 235 will stop the program 
with the message 


TILLEGAL QUANTITY ERROR 
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5.2.2 


PR INT writes to the current output 
device 


current output device: see Section 
5.2.1 


number formats: see Section 5.2.3 
SPC function: see Section 5.2.4 


TAB function: see Section 5.2.4 


Semicolon suppresses space after an 
item 


The PRINT Statement 


PRINT 

PRINT P$+ Q+ R& 

PRINT "DISCRIMINANT = "3 B°Z - 4#AxC 

PRINT LEFT# (FNS+ 1) + "4" + LNG 

PRINT TAB (M)$ "*¥" TAB (M + ND 3 
"eee" TAB (M + N + NDE "He" 


The PR INT statement writes output to the current output device. 
Expressions representing the values to be written are listed after the 
keyword Pk INT, separated by commas or semicolons. 


Any expression may be included ina PR INT statement. Each 
expression in the list following the keyword PR I NT is evaluated. If 
the value of the expression is a string, the characters of the string are 
written to the current output device; if the value is a number, it is writ- 
ten according to the rules discussed in Section 5.2.3, “Number For- 
mats.” Calls to the special functions 5PC and TAB may also be 
included ina PRINT list; they do not cause anything to be written, 
but control the positioning of the next item. 


When an item in the PR INT list is followed by a semicolon, the cur- 
sor (if output is going to the screen) or print head (if to a printer) is left 
positioned immediately after the last character in the item. The next 
item written will begin in the next available column, with no interven- 
ing spaces. A semicolon at the end ofa PR INT statement causes 
the cursor or print head to be left at the end of that line, and prevents 
a new line from being started. For example, the statement 


PRINT 13 


23 335 43 
will produce the output 


and will leave the cursor or print head positioned in the column imme- 
diately following the digit 4. The statement 


PRINT i/3: (2 8 4)3 
will produce the output 


5232933995851 


Output 








lf two consecutive items ina PRINT list are not separated by either a 
comma or asemicolon, a semicolon is understood. 


The Apple lle’s normal display is 40 columns wide. After Applesoft dis- 
plays the 40th character on a line, it automatically sends the cursor to 
the beginning of the next line. The next PX I NT statement executed will 
start another new line, causing an unintended blank line to appear on 


80-Column Text Card: see Apple Ile the screen. This happens even if you have the Apple Ile 80-Column Text 

Owner's Manual, Apple Ile 80-Column Card installed and running in “active 80” mode; Applesoft doesn't know 

Text Card Manual about the 80-column display and will still break each output line after 40 
characters. 


For example, the statements 

10 PRINT “THIS MESSAGE HAS PRECISELY 40 
CHARACTERS" 

20. PRIM: "SO. THERE’ SA BLANK LINE ON THE 
Sake i” 

will display the output 

THIS MESSAGE HAS PRECISELY 40 CHARACTERS 

SC THERES FA OOULANA LINE UN THE SCREEN 


To eliminate the blank line, add a semicolon to the end of line i ©: 


LO PRIS "TALS MESSAGE HAS PRECISELY 40 
CHARACTERS" 5 


Now you'll get this: 


THLS MESSAGE HAS PRECIGELY SO. CHARACTERS 
DU THERES “A BLANK LINE ON: THE SCREEN 


The second line of this message is now a lie. 


A statement such as 
PRINT AS + Bt 
causes a halt with the message 
PSTRING TOO LONG ERROR 
concatenation: see Section 4.2.2 if the combined length of the concatenated strings is greater than 255. 
However, you can print the apparent concatenation regardless of length 


by using a semicolon: 


PRINT As BS 
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Comma advances to next tab position 


80-Column Text Card: see Apple Ile 
Owner's Manual, Apple Ile 80-Column 
Text Card Manual 


text window: see Section 5.2.4, Section 
F.1, and the Apple Ile Reference Manual 


PR INT by itself starts a new line 





When an item inthe Pk INT list is followed by acomma, the cursor 
or print head is advanced to the next available tab position: column 
17 or 33 of the current line or column 1 of the next line. The next item 
written will begin at the tab position. A series of consecutive commas 
will advance the cursor or print head a corresponding number of tab 
positions. Acomma at the end of a PRX INT statement causes the 
cursor or print head to be left at the next available tab position, and 
may prevent a new line from being started. For example, the 
statement 


PRINT d+ 2+ G+ 4+ 
will produce the output 


and will leave the cursor or print head positioned in column 17 of the 
second line, directly under the digit 2. The statement 


PRAM? if/or (2 % Gis Oo 
will produce the output 


lf any character appears in columns 24 to 32, or if you have the Apple lle 
80-Column Text Card installed in your computer and running in “active 
80” mode, then column 33 is not available as a tab position; acomma 
after column 17 will cause the next item to start at column 1 of the next 
line. 


If the text window is set to fewer than 33 columns wide, commas ina 
PR INT statement do not function properly and may cause text to be 
displayed outside the text window. 


A PRINT statement that doesn’t end with acomma or semicolon al- 
ways starts a new line after writing its last item and leaves the cursor 
or print head positioned in column 1 of the new line. The statement 


PRINT 


simply starts a new line. If the cursor or print head was already at the 
beginning of a line, this statement causes a blank line to be displayed 
or printed. 
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* stands for PRINT 








Here’s an example program using some of the features of PR INT 
discussed above: 


1G LET A = Sed 2: LET CS = "FRED" #& LET 
GA = 16 —set up series of variables 
£0 PRINT "STUFF AND NONSENSE" 
—display message and start 


new line 

30 PRINT —display a blank line 

40 PRINT "QA = "4 —display message without start- 
ing anew line 

oO PRINT &A —display 3+ 33 onsame line as 


message from program line 
40: start new line 


60 PRINT "Gi = “+s G% —display message and value 
16 onsame line; start new 
line 

7Q PRINT "C% = "y+ (€% M—display message, advance to 


next tab position, and display 
string F RED; start new line 

80 PRINT A * G&A —display value of expression 
A * G4(83.6)andstart 
new line 


When executed, this program will produce the following output: 


STUFF AND NONSENSE 

A = Sega 

G% = 16 

Cs = FRED 
83.6 


Abbreviation: You can use a question mark (‘) as an abbreviation for 
the keyword PRINT; if you use it, it appears as PR INT ina program 
listing. If you type 


100 ? AS —display string A$ 
ae —list program 


Applesoft will display 
100 PRINT A¢ —Applesoft sees * as PRINT 
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5.2.3 


Ranges of numeric values 


All arithmetic done on reals 


truncate: to convert a real number to the 
next lower integer 


Rules for number formats 


Number Formats 


This section describes the formats in which Applesoft displays or 
prints numeric values. Numbers may not always be formatted in the 
way you might expect; this is particularly true for numbers more than 
nine digits long or for exceptionally small numbers. 


Numeric values in Applesoft must be inthe range — 1*10° 38 to 
1* 10° 38. Any number whose absolute value is less than approxi- 
mately 3% 10” — 39 is converted to zero. True integer values to 

be assigned to integer variables (Such as A 4%.) must be in the range 
~32767to+32767. 


A number typed from the keyboard or a numeric constant used in an 
Applesoft program may have as many as 38 digits. However, only 
nine digits are significant, and the last digit is rounded off. An Apple- 
soft statement that you type as 


PRINT 1.23456787/65432i1 


—you type this from the 
keyboard 
will display 
+2£3456788 —you get this on the screen 
on the screen. 


Integers are always converted to real form before being used in arith- 
metic calculations, and the results are converted back to integer form 
when assigned to an integer variable. Conversion from real to integer 
form is by truncation to the next lowest integer, not by rounding to the 
nearest integer. 


Applesoft displays and prints numbers according to the following 
rules: 


@ Ifthe number is negative, it is preceded by a minus sign (-); if itis 
zero or positive, no sign is used. 


@ Ifthe number is an integer with an absolute value from © to 
J399 339 99, itis formatted as an integer. 


Output 








Table 5-1 Number Formats 


scientific notation: the representation 
of numbers in terms of powers of 10 


Figure 5-1 Format for Scientific Notation 


sign exponent symbol 


wi Wye yeaa 
ry ¢ KRAAKAAAAE ODD 


each x is adigit 


sign of exponent 


digits of exponent 


118 


@ Ifthe number is not an integer and its absolute value is between 
*OQland93s 899 83s. =, itis formatted with a decimal 
point in the usual way. 


@ Inall other cases, the number is formatted in scientific notation 
(see below). 


Table 5-1 shows examples of the formats used for displaying and 
printing numbers. 


Number Output Format 
+7 1 
—1 =] 
6523 6323 
— 23.460 —239+46 
45.72 #10°5 4372000 
1* 10°20 lE +20 
— 12.34567896 * 10° 10 =—1 1280565 (SE + 7a 
1000000000 LE +Oo 
999999999 HHSeeggrs 


The format Applesoft uses for scientific notation is shown in Figure 
5-1. Asign is shown only if the number is negative. There is always 
exactly one nonzero digit before the decimal point and up to eight dig- 
its after it, with trailing zeros suppressed. There are never any lead- 
ing zeros; the digit before the decimal point is always nonzero. If 
there is only one digit to print after all trailing zeros are suppressed, 
no decimal point is shown. The letter E (for ‘““exponent”) is always 
followed by a sign and a two-digit exponent. The value of a number 
represented in this form is the number before the E times 10 raised to 
the power after the E. For example, 


PRINT 3S # G45 * 14 ylelds 1,18430085E+37 
PRINT -3.14139 * S67 ~ 3 

yields -1,841046659E+14 
PRAiNT 3 ¢ obs yields 1,O001001E-03 
PRINT -3 / Gas yields -3.003003E-03 
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5.2.4 


POKE statement: see Section 7.1.2 


TEXT switches from graphics to text 
display 


text window: see below 
80-Column Text Card: see Apple Ile 


Owner's Manual, Apple Ile 80-Column 
Text Card Manual 


HOME clears the text window 


text window: see below 


Formatting Text on the Screen 


This section deals with Applesoft’s facilities for controlling the way 
text is formatted and presented on the display screen. For further in- 
formation on text formatting, see Section 5.2.2, “The PRINT 
Statement.” 


The TEXT and HOME statements are used to clear text and graph- 
ics from the screen. 


SPC, TAB, HTAB, ¥TAB, and PQS control the position of the cur- 
sor, which determines where characters are displayed on the screen. 


NORMAL, INVERSE, andFLASH control the form in which text 
characters are presented on the screen. 


The SPEED = command sets the rate at which characters are 
displayed. 


The POKE statement can be used to set the boundaries of the text 
window within which text is displayed on the screen. 


The TEXT Statement 
TEXT 


The TEXT statement instructs Applesoft to begin displaying text on 
the screen; it is usually used to switch from graphics to text display. 
The text window is set to the full screen (24 lines, 40 characters per 
line; 80 if the 80-Column Text Card is installed and running in “active 
80” mode). The Applesoft prompt character (1) is displayed in the 
bottom-left corner of the screen, followed by the cursor. 


If the display is already in text mode, the TE XT statement is equivalent 
tothe statement VTAB 4 (see “The TAB Statement,” below). 


The HOME Statement 
HOME 


HOME clears the currently defined text window and sends the cur- 
sor to the top-left corner of the window. If the text window is set to 
the full screen, the cursor is sent to the beginning of line 1. If the 
computer is displaying mixed text and graphics (four lines of text at 
the bottom of the screen), HOME clears the four text lines and 
sends the cursor to the beginning of line 21. 
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JTAB and HT AB statements: see 
below 


SPC displays spaces on the screen 


PRINT statement: see Section 5.2.2 


TAB function: see below 


current output device: see Section 
5.2.1 


SPC atend of PR INT suppresses new 
line 





Helpful Hint: To move the cursor to the top-left corner of the screen 
without clearing any text, use 


VTAB 1 : HTAB 1 


The SPC Function 


The SPC (for “space”) function is used in Pk INT statements to 
write a specified number of spaces to the current output device. The 
numeric argument given to the function specifies the number of 
spaces to be written. If this value is a real number, Applesoft trun- 
cates it to the next lowest integer. 


The SPC function can be called only from withina PR INT state- 
ment. SPC differs from T AB in that it advances the cursor (or print 
head, if the current output device is a printer) a specified number of 
columns from its current position, rather than to a specific horizontal 
position from the beginning of the current line. If the cursor is spaced 
past the right edge of the screen or text window, it returns to the be- 
ginning of the next line and continues spacing. For example, assum- 
ing the text window is set to the full screen and the cursor is initially at 
the left edge, the statements 


10 PRINT SPL ¢323 "HELLO" 
—display HELLO starting in 
column 6 
20 PRINT "THESE"? SPC (10)5 "“ARE*: SPE 
(4)3 "INTERESTING"; SPC (12)3 
‘TIMES® —display THESE, 10 
spaces, ARE, 4 spaces, 
INTERESTING, 12 spaces, 


TIMES 
will display the following on the screen: 
HELLO 
THESE ARE INTERESTING 
TIMES 


Notice how the output of line 2 © “wraps around” when it reaches the 
edge of the screen (column 40). 


lf SPC is the last item ina PRINT statement, Applesoft acts as if the 
statement ended with a semicolon. The cursor is left positioned the 
specified number of spaces after the end of the previous item; no new 
line is started. The next item displayed will begin immediately following 
the last space. 
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TAB advances cursor to a specified 
horizontal position 


PRINT statement: see Section 5.2.2 


SPC function: see above 


current output device: see Section 
5.2, 





The argument given to SPC must be in the range @ to 233 or the pro- 
gram will halt with the message 


PTILLEGAL QUANTITY ERROR 
However, several calls to SPC can be strung together in the form 
PRINT SPC(2ZG5): SPUL2537: SPli ess) 


to provide arbitrarily large numbers of spaces. 


Semicolons are optional between SPC items: 


PRINT “LET s SPro. (10). "ALL. 
PRE oe 


ar (15).4 


The TAB Function 


The T AB function is used in PR INT statements to advance the cur- 

sor to a specified horizontal position from the beginning of the current 
output line. The numeric argument given to the function specifies the 

position to which the cursor is to be moved. If this value is a real num- 
ber, Applesoft truncates it to the next lowest integer. 


The T AB function can be called only from within a PR INT state- 
ment. TAB differs from SPC in that it advances the cursor (or print 
head, if the current output device is a printer) to a specific horizontal 
position from the beginning of the current line, rather than a specified 
number of columns from the current cursor position. If the cursor is 
advanced past the right edge of the screen or text window, it returns 
to the beginning of the next line and continues advancing. For exam- 
ple, assuming the text window is Set to the full screen and the cursor 
is initially at the left edge, the statements 


10 PRINT TAB (15)5 "THE FLEET‘’S INI" 
—display THE FLEET‘’S IN! 
starting at column 15 
"HELLO" 3 TAB (30)5 
(43)3 "SAILOR!" 
—display HELLO atcolumn 10, 
THERE + atcolumn 30, 
SATLOR! atcolumn5of 


next line 


£0 PRINT TAB (10)5 
"THERE +" 5 TAB 


will display the following on the screen: 
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Notice how the output of line = “wraps around” when it reaches the 
edge of the screen (column 40). 


HT AB statement: see below Unlike the HT AB statement, which moves the cursor to an absolute hor- 
izontal position from the left edge of the screen or the text window, TAB 
moves the cursor in a forward direction only. If the specified tab position 
is less than the current cursor position, T AB has no effect; it will never 
move the cursor to the left on the current line (use HT AB for this 
purpose). 


TAB at end of PR INT suppresses new If TAB is the last item ina PR INT statement, Applesoft acts as if the 

line statement ended with a semicolon. The cursor is left at the specified tab 
position; no new line is started. The next item displayed will begin at the 
tab position. 


The argument given to TAB must be in the range © to 235 or the pro- 
gram will halt with the message 


FILLEGAL QUANTITY ERROR 


An argument value of @ moves the cursor to 256 positions from the be- 
ginning of the current line. 


Semicolons are optional between T AB items: 


PRON, "DEAN +. -7AR f24)) POU". Tae (27) + "GO" 


The HTAB Statement 


HTAB 10 
HTAB N 
HTAB 41 - LEN (5%) 


HT AB moves cursor to a specified H TAB (for “horizontal tab”) moves the cursor to a specified horizon- 

horizontal position tal position from the beginning of the current output line. The expres- 
sion following the keyword HT AB specifies the position to which the 
cursor is to be moved. If this value is a real number, Applesoft trun- 
cates it to the next lowest integer. 
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TAB function: see above 


H TAB can move cursor in either 
direction 


text window: see below 





Unlike the T AB function, which moves the cursor in a forward direc- 
tion only, the H TAB statement can move the cursor in either direction 
to a specified horizontal position. For example, the program 


> HOME —clear text from screen 
10 HTAB G : PRINT "IS THE “3 
—display [5S THE starting at 
column 6 
15 FOR 2 = 1 TQ 300: NEAT 2 
—delay loop so user can see the 
order and position of text 
display 
£0 HTAB 1 o: PRINT "THIS “3 
—display THIS atcolumn 1 
£o FOR 2 = 1 TO 300 : NEAT 2 
—another delay loop 
30 HTAB 13 : PRINT "PROPER ORDER" 
—display PROPER ORDER at 
column 13 


will display the following on the screen: 


If you want to use HT AB to display several text items on the same line, 
you need a semicolon at the end of each PR INT statement, as in the 
program above, to avoid starting a new line. 


If there is a text window set, the specified tab position is interpreted 
relative to the left edge of the window. However, H TAB behaves as 
though there were 40 columns in each line of the window, regardless 
of the actual width to which the window has been set; that is, position 
1 is considered to be the leftmost column of the current line, position 
41 the leftmost column of the next line, position 81 the leftmost col- 
umn of the line after that, and so on. If the cursor is advanced past the 
right edge of the screen or text window, it returns to the beginning of 
the next line and continues advancing. 


H T AB can carry the cursor outside the boundaries of the text 
window, but only long enough to display one character; the cur- 
sor then returns to the left edge of the window. 





80-Column Text Card: see Apple /le 
Owner’s Manual, Apple Ile 80-Column 
Text Card Manual 


POKE statement: see Section 7.1.2 


‘JT AB moves cursor to a specified 
vertical position 








80-Column Text Card Users: HT A&B is designed to operate with a 
40-column screen only. If you attempt to advance the cursor beyond 
column 40, it will “wrap around” to the next line, even if you have the 
Apple Ile 80-Column Text Card installed and running in “active 80” 
mode. To tab to a position between columns 41 and 80, use 


POKE 36% AA 


where * the number of the column to which you want to tab. See 
Section F.1 and the 80-Column Text Card Manual for more information. 


The column number specified to H TAB must be in the range © to 235 
or the program will halt with the message 


PILLEGAL QUANTITY ERROR 


A value of ® moves the cursor to 256 positions from the beginning of the 
current line. 


Many programmers find H T AB to be more convenient to use than TAB, 
because it is an independent statement and need not be embedded ina 
PR INT statement. This makes it easier to change, if necessary, during 
program development. 


The J TAB Statement 


VTAB 10 
VTAB N 
VTAB £3 - Ha 


\) TAB (for “vertical tab”) moves the cursor vertically to a specified 
line on the screen. The expression following the keyword J TAB 
specifies the line to which the cursor is to be moved. If the value of 
this expression is a real number, Applesoft truncates it to the next 
lowest integer. 


The top line of the screen is line 1; the bottom line is line 24. J TAB 
may move the cursor either up or down on the screen, but never to 
the left or right; it remains at the same horizontal position as before 
the move. For example, 


1 FUME —clear text from screen 
-0O YVTAB 6 —move cursor to line 6 
30 PRINT "LINE 6" —display imaginative message 
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Text window ignored 


POS yields current horizontal cursor 
position 


Argument required but ignored 


40 FOR 2 = 1 TO 300 : NERKT 2 
—delay loop so user can see the 
order and position of text 
display 
20 YTAB 18 —move cursor to line 18 
GO PRINT "LINE 18" | —display another imaginative 
message 
70 FOR 2 = 1 TQ 300 : NEAT 2 
—another delay loop 
80 VTAB le —move cursor to line 12 
90 PRINT "THE MIDDLE" —display last message 


\) TAB ignores the setting of the text window, if any. The specified line 
number is always taken to refer to the entire screen. 


The line number specified to '4 T AB must be in the range i to 24 orthe 
program will halt with the message 


TILLEGAL QUANTITY ERROR 


lf '¥ T AB moves the cursor to a line below the bottom of the text window, 
all subsequent text will be displayed on that same line. 


The POS Function 


The POS (for “position”) function yields the current horizontal posi- 
tion of the cursor, relative to the left edge of the screen or text window. 
The value yielded is in the range ® to 39 (9 to 79 ifthe Apple lle 
80-Column Text Card is installed and running in “active 80” mode). A 
value of represents the left edge of the screen or window. 


Strange but True: The argument given to PQS is ignored, and has no 
effect on the operation of the function. However, you can't leave it out— 
you must include an argument expression of some kind to “keep the pa- 
rentheses apart.” What you use for an argument expression doesn't 
matter, but if Applesoft can’t evaluate it as a legal expression, you'll get 
an error halt. 
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POS, TAB, and HT AB disagree 


INVERSE displays text in black-on- 
white 


NORMAL statement: see below 


Pk INT statement: see Section 5.2.2 








A Difference of Opinion: Notice that POS numbers columns beginning 
with 0, whereas TAB and HT AB number them beginning with 1. Thus, 
assuming the cursor is at the beginning of a line, the statement 


PRINT TAB (10)5 POS (0) —tabtocolumn 10 and display 
position 


will display the value 9, and 


HTAB 43. 2 PRINT.PUS: (x 
—tab to column 43 and cisplay 
position 


will display = (since HTAB 43 tabs to the third column of the next dis- 
play line). Notice in the second case that the value of variable “% makes 
no difference. 


The INVERSE Statement 
INVERSE 


The INVERSE statement causes subsequent text output to be 
displayed in black-on-white instead of the usual white-on-black 
(where “white” means the phosphor color of your display, whatever 
that is). The normal white-on-black display can be restored with the 
NORMAL statement. For example, 


10 INVERSE —set inverse display 
£9 PRINT "“BLACK-ON-WHITE" 
—display BLACK -ON- 
iH [ TE in black-on-white 
30 NORMAL —restore normal display 
40 PRINT "“WHITE-ON-BLACK" 
—display WHI TE-ON- 
BLACK in white-on-bdlack 


INVERSE affects only subsequent output characters sent to the 
screen with Pik INT statements. It has no effect on characters al- 
ready on the screen or on keyboard input “echoed” to the screen. 


Don’t Overdo It: INVERSE is most effective when you use it sparingly. 
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FLASH causes text to flash on the 
screen 


NORMAL statement: see below 


PRINT statement: see Section 5.2.2 


ASCIl codes: see Section 4.2.1 and 
Appendix C 


80-Column Text Card: see Apple /le 
Owner’s Manual, 80-Column Text 
Card Manual 


The FLASH Statement 
FLASH 


The FLASH statement causes subsequent text output to alternate 
approximately twice a second between black-on-white and the usual 
white-on-black (where “white” means the phosphor color of your dis- 
play, whatever that is). The normal white-on-black display can be re- 
stored with the NORMAL statement. For example, 


10 FLASH 
£0 PRINT 
30 NORMAL 
40 PRINT 


"FLASHY" 


MHRAB" 


—set flashing display 
—display flashy FLASHY 
—restore normal display 
—display drab DRAB 


FLASH affects only subsequent output characters sent to the 
screen with Pik INT statements. It has no effect on characters al- 
ready on the screen or on keyboard input “echoed” to the screen. 


FLASH doesn’t work on characters with ASCII codes above 33, the 
most important of which are the lowercase letters; instead of making 
them flash, it turns them into gibberish. F L ASH doesn’t work at all if you 
have the Apple Ile 80-Column Text Card installed and running in “active 


80” mode. 


A Little Dab’II Do Ya: FL. ASH is most effective when you use it very 
sparingly. Reserve it for only the most important messages or unusual 
uses. Cavalier use of FL. ASH has been known to drive users to 


delirium. 


Output 





NORMAL displays text in white-on- 
black 


INVERSE andFLASH statements: 
see above 


Pl INT statement: see Section 5.2.2 


SPEED = sets rate of text output 





The NORMAL Statement 
NORMAL 


The NORMAL statement causes subsequent text output to be dis- 
played in the usual white-on-black (where “white” means the phos- 
phor color of your display, whatever that is). It is usually used to 
cancel the effects of the INVERSE or FLASH statement. For 
example, 


10 INVERSE —set inverse display 
20 PRINT "“BLACK-ON-WHITE" 
—display BLACK -ON- 
WH I TE in black-on-white 
30 NORMAL —restore normal display 
40 PRINT "“WHITE-ON-BLACK" 
—display WHITE -ON- 
BLACK in white-on-black 


20 FLASH —set flashing display 

GO PRINT "FLASHY" —display flashy FLASHY 
70 NORMAL —restore normal display 
80 PRINT "DRAB" —display drab DRAB 


NORMAL affects only subsequent output characters sent to the 
screen with Pik INT statements. It has no effect on characters al- 
ready on the screen. 


The SPEED= Statement 


Sree £20 
SPEED= A 
SPEED= 2 - G6 * F 


The SPEED = statement sets the rate at which output characters 
are sent to the display screen or other output device (Such as a 
printer). The slowest rate is ©; the fastest is 235. The normal speed 
setting (if you don’t do anything to change it) is 235. For example, 


10 SPEED= 0 —set slowest possible speed 
£9 PRINT "THE TORTOISE" 
—display THE TORTOISE 


slowly 
30 SPEED= 23. —restore normal speed 
40 PRINT “THE HARE" = —display THE HARE quickly 


Input/Output 





SPEED isn'ta variable 


POKE statement: see Section 7.1.2 


5.2.5 


PEEK function: see Section 7.1.1 


POKE statement: see Section 7.1.2 


Notice that the equal sign is part of the keyword SPEED =; it doesn’t 
represent an assignment to a variable named SPEED. A statement 
such as 


LET SPEED = A 


will cause a syntax error. The only way to find out the current speed 
setting is to keep track of it yourself with a variable, as in the following 
example: 

LO LeEl A = £30 —set initial value for speed 
29 SPEED= & —set speed to value of * 


SO PRINT "“CURKENT SPEED [5 "s: aA 
—display current speed 


MO Let %® = A - 2o —decrease value of X by 23 
oO IF A >= O08 THEN GOUIOC Zo 
—repeat until X becomes 
negative 
SO SPEED= 2353 +: END — 7 is too low; end the program 


The speed setting is not reset to its normal value by RUN, CLEAR or 


[CONTROL }-[RESET 


The speed setting specified to SPEED = must bein the range ® to 
=<. or the program will halt with the message 


TILLEGAL QUANTITY ERROR 


The Text Window 


The “window” within which text is displayed and scrolled on the 
screen can be set to less than the full screen through the magic of the 
POKE statement. See Section F.1 for details and the Apple //e Refer- 
ence Manual for a more technical discussion. 





Miscellaneous Output Facilities 


This section covers Applesoft’s facilities for dealing with the remain- 
ing output features of the Apple Ile: the built-in speaker, annunciator 
outputs, utility strobe, and cassette tape output. Most of these fea- 
tures are controlled by means of PEEK and POKE; details can be 
found in Appendix F, “Peeks, Pokes, and Calls.” The annunciators 
and utility strobe are seldom used, and are mentioned here just for 
the sake of completeness. 


Output 





CONTROL |-G sounds the “bell” 








Controlling The Speaker 


The Apple Ile has a small, built-in soeaker that you can use to add 
sound to your programs. The easiest way to use it is by sending the 
ASCII “bell” character ({ CoNnTROL |-G, ASCII code 7) to the display 
screen. This causes the computer to emit a short “beep.” 


Historical Note: ASCII code 7? was originally used to ring a small bell on 
teletype machines, to let the teletype operator know that a message was 
coming in. On the Apple Ile it sends a 1-kilohertz tone (1000 cycles per 
second) to the computer’s speaker for 1/10 second. 


Here’s a program to ring the computer's “bell” a number of times 
specified by the user: 


ii} 


J 


3 


30 


Ao 


it) 


GO 
70 
8) 
90 


"ENTER A NUMBER FROM 1 TO 9 


(S TQ STOP):" +s | —promptuser for input 


—accept single character from 
keyboard 
= "S" THEN END 
—stop if user typed 5 
(A$) < 1 THEN 20 
—if character typed is out of 
range then try again 
= 1 TO VAL (AG) 
—loop requested number of 
times 
CHRE (7) —sound “bell” 
—loop back to 30 
—leave a blank line 


GOTO 10 —start again 


The only other way to produce sound from the speaker is with a 
PEEK or POKE to address - 16336. This causes the speaker to 
emit a single “click.” By combining such clicks in the appropriate pat- 
terns and frequencies, you can produce musical tones and a variety 
of other sounds. Experiment for yourself! 


For technical information on the built-in speaker, see the Apple Ile 
Reference Manual. 
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annunciators: see Apple //e Reference 
Manual 


utility strobe: see Apple Ile Reference 
Manual 


SAWE command: see Section 1.2.5 and 
Appendix M 


STORE statement: see Appendix M 


Annunciator Output 


The Apple Ile has four annunciator outputs, which are pins of the 
hand control connector on which electrical impulses can be transmit- 
ted. The signals on these pins are most commonly used to control 
devices such as lamps and relays connected to the computer 
through the hand control connector. The annunciator outputs can be 
turned on and off with PEEK or POKE to the appropriate addresses; 
see Section F.4 for details and the Apple Ile Reference Manual for 
further technical information. 


The Utility Strobe 


The Apple Ile’s utility strobe is a pin of the hand control connector that 
can be triggered to send an electrical impulse lasting one-half micro- 
second. Like the annunciators, it can be used to control a variety of 
devices connected to the computer through the hand control connec- 
tor. The utility strobe can be triggered witha PEEK or POKE to ad- 
dress - 16320; see Section F.4 for details and the Apple Ile 
Reference Manual for further technical information. 


Cassette Output 


Two Applesoft statements, SAVE and STORE, canbe used to write 
information to a cassette tape recorder. SAVE writes the Applesoft 
program currently in memory to tape; 5 TORE writes the contents of 
an integer or real array. For details, see Appendix M, “If You Have a 
Cassette Recorder.” 
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low-resolution graphics: see Section 
6.1 


high-resolution graphics: see Section 
6.2 


shape tables: see Section 6.3 


6.1 


GR statement: see Section 6.1.1 
COLOR = statement: see Section 6.1.2 


PLOT statement: see Section 6.1.3 
HL IN statement: see Section 6.1.4 
WL IN statement: see Section 6.1.5 


SCRN function: see Section 6.1.6 


Graphics 


This chapter describes Applesoft’s facilities for creating, changing, 
displaying, and storing both low- and high-resolution graphic 
designs. 


Section 6.1, ‘“Low-Resolution Graphics,” deals with 16-color graphics 
ona 40-by-48 grid. 


Section 6.2, “High-Resolution Graphics,” deals with 6-color graphics 
ona 280-by-192 grid. 


Section 6.3, “Shape Tables,” discusses the use of shape tables for 
animation sequences. 


Low-Resolution Graphics 


The low-resolution graphics screen consists of 1920 blocks (40 col- 
umns by 48 rows) in 16 colors. This section describes the facilities 
available in Applesoft for using low-resolution graphics: 


e@ The GR statement instructs Applesoft to begin displaying low- 
resolution graphics. 


@ The COLOR = statement controls the colors displayed onthe 
screen. 


@® The PLOT statement plots individual blocks on the screen. 
@® The HLIN statement draws horizontal lines. 
@e The ¥iIN statement draws vertical lines. 


@ The SCN function determines what color is currently displayed 
at any position of the screen. 
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GR displays low-resolution graphics 


TEXT statement: see Section 5.2.4 


text window: see Section 5.2.4 


POKE statement: see Section 7.1.2 


high-resolution page 2: see Section 
6.2.2 


For more information... 








The GR Statement 
GR 


The GR (for “graphics”) statement instructs the computer to display 
low-resolution graphics. If the screen has been displaying text, it is 
changed from 40 (or 80) columns by 24 lines of text to 40 columns by 
40 rows of graphics, with space for four lines of text at the bottom. 
(Full text display can be restored with the TE «T statement.) GR 
clears the screen to black, moves the text cursor to the beginning of 
the bottom line (line 24), clears any text window that may have been 
set, and sets the low-resolution display color to ® (black). 


After executing a GI¥ statement, you can convert the display to full- 
screen graphics (a 40-by-48 grid with no space for text) with the 
statement 


POKE -16302 +0 


This statement will change the bottom four lines of text to eight rows 
of colored blocks. To clear these rows to black, add 


CALL -19538 


Notice that the POKE statement above must be executed after GF. If 
you execute the POKE first, GF will reset the screen to mixed graphics 
and text. 


If you execute a GR statement while displaying high-resolution page 2, 
GF clears its usual screenful of memory but leaves you looking at page 
2 of low-resolution graphics and text. To avoid this problem, always use 
the TEXT statement before switching from high-resolution page 2 to 
low resolution. 


See Section F.3 for more information on the use of the various text and 
graphics memory pages. See the Apple Ile Reference Manual for fur- 
ther technical information on the Apple Ile’s graphics display 
Capabilities. 
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COLOR = sets low-resolution display 
color 


Table 6-1 Color Codes for Low-Resolu- 
tion Graphics 


HL IN statement: see Section 6.1.4 


The COLOQR= Statement 


COLOR= le 
COLOR= CJ) 
COLOR= (xX - 4) / 16 


The COL OR = statement sets the display color for plotting low- 
resolution graphics. There are 16 colors available, represented by 
numbers from ® to 13 as shown in Table 6-1. When youenter — 
low-resolution graphics, the GF statement sets the display color to 
black (@). 


Code Color Code Color 
Q black 8 brown 
1 magenta | orange 
= dark blue 10 grey-2 
3 violet Li pink 
4 dark green 12 green 
2 grey-1 1 yellow 
6 medium blue 14 aqua 
7 light blue be. white 


If you’re using a monochrome display (black-and-white, or some other 
single phosphor color), the different colors will appear on your screen as 
various patterns of shading. 


The following short program displays each of the 16 available colors 
in a horizontal bar across the screen: 


10 GR —display low-resolution 
graphics 

209 FOR K = 0 TQ 15 —execute loop for each color 

30 COLOR= & —set next color 


40 HLIN O+ 39 AT K ¥* 2 
—draw a bar of this color across 
the screen, leaving a blank 
row above it 
oO NEXT &A —go back for next color 
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COLOR isn’t a variable 


PLOT draws a single block 


low-resolution display color: see 
Section 6.1.2 





Notice that the equal sign is part of the keyword COL OF =; it doesn’t 
represent an assignment to a variable named COLOR. A statement 
such as 


LET COLOR= & 


will cause a syntax error. The only way to find out the current display 
color is to keep track of it yourself with a separate variable, as in the 
example above. 


You can specify a color code higher than i 3, but the series of color val- 
ues simply repeats. Thatis, 16 is equivalent to 0, 18 is equivalentto 2, 
33 is equivalent to 3, and so on. However, a color value less than © or 
greater than =35 will stop the program with the message 


TILLEGAL QUANTITY ERROR 





The PLOT Statement 


PLOT 20% 12 

PLUT A» Ge ¥ + «@ 

PLOT THETA * 40 / (2#PI)+ 24 - 
LOIN TIARA? © a2 


The PLOT statement places a block of the current low-resolution 
display color at a specified position on the screen. The first expres- 
sion following the keyword PLOT specifies the column in which the 
block is to be plotted (numbered © to 39, from left to right); the sec- 
ond expression, separated from the first by acomma, designates the 
row (numbered © to 39 for mixed text and graphics, © to 4? for full- 
screen graphics, from top to bottom). For example, the following pro- 
gram plots a block of pink in column 20, row 2 of the screen: 


10 GR —display low-resolution 
graphics 

£9 COLOR= il —set display color to pink 

30 PLOT 20+ 2 —plot a block of pink in column 


20, row 2 


Figure 6-1 shows the system of coordinates used to designate posi- 
tions on the low-resolution graphics screen. Position © + © is the top- 
left corner and position 39 +© the top-right. When displaying mixed 
graphics and text, the bottom-left corner is position @ +39 andthe 
bottom-right is 35 +33); in full-screen graphics, the bottom-left cor- 
neris O +47 andthe bottom-rightis 39 +47. 
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Figure 6-1 Screen Coordinates for Low- 
Resolution Graphics 


Oy 0 39, 0 
Oy Jo woe 3G 
(orQ+ 47) (or 32% 47) 


lf Applesoft is displaying mixed graphics and text and the plotting coordi- 
nates designate a row from 40 to 47, a text character will be displayed 
at the specified coordinates instead of a block of color. The particular 
character displayed depends on the current low-resolution display color. 
Here’s a program to demonstrate this effect: 


10 GR —display mixed low-resolution 
graphics 

20 FOR + = © 1d 47 —loop over all screen rows 

20 FUR KR = 0 iG 2o —l|oop over all screen columns 

“0 COLOR = A —use color corresponding to col- 


umn number (colors 0 to 15 will 
repeat after column 15) 


SO PLOT Ae Y —plot a block at column X, row Y 
GO NEXT A —loop to next column 
70 MEAL. YX —loop to next row 


Try changing line 1 © to 

10 Lex 

to see the effect on the full screen. 

A column coordinate outside the range ® to 39 or a row coordinate out- 
side the range © to 4 7 will cause the program to halt with the message 


PILLEGAL GUANIIIY ERROR 





61.4 The H_LIN Statement 


HLIN 3+ 20 AT 35 
HLIN A+ ¥Y AT 2 
HLIN 9 - 3+ J * 58 AT VUE 


HL IN draws a horizontal line The HL. IN (for “horizontal line”) statement draws a horizontal line on 

ee the screen in the current low-resolution display color. The two expres- 

Santon ed S sions following the keyword HL. IN, separated by acomma, desig- 
nate the columns in which the line is to begin and end; the expression 
following the keyword AT specifies the row in which the line is to be 
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WL IN draws a vertical line 


low-resolution display color: see 
Section 6.1.2 





drawn. The first end point may be less than, equal to, or greater than 
the second. For example, 


10 GR —display low-resolution 
graphics 

£9 COLOR= 4 —set color to dark green 

30 HLIN 10+ 30 AT 20 —drawahorizontal green line in 
row 20 from column 10 to col- 
umn 30 


If you use HL. IN while displaying text instead of graphics, or with a row 
coordinate from 40 to 47 while displaying mixed graphics and text, 
Applesoft will display a row of characters instead of a bar of color. For 
example, if line 1 above were changed to 


40 TEA —display text instead of graphics 
the result would be a row of dollar signs instead of a bar of dark green. In 


most cases, when you see patterns like these on your screen it means 
you forgot to include a GR statement. 


A column coordinate outside the range © to 39 or a row coordinate out- 
side the range © to 4 7 will cause the program to halt with the message 


FILLEGAL QUANTITY ERROR 


The HL. IN statement has no visible effect if you use it while displaying 
high-resolution graphics. 





The 'JLIN Statement 


VLIN 3+ 20 AT 35 
VLIN As ¥ AT 2 
VLIN QO - 3+ J * 58 AT VE 


The ¥L IN (for “vertical line”) statement draws a vertical line on the 
screen in the current low-resolution display color. The two expres- 
sions following the keyword '/L. I N, separated by acomma, dlesig- 
nate the rows in which the line is to begin and end; the expression 
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SCRN reads the color at a designated 
screen position 


color codes: see Table 6-1, Section 


following the keyword AT specifies the column in which the line is to 
be drawn. The first end point may be less than, equal to, or greater 
than the second. For example, 


10 GR —display low-resolution 
graphics 

£9 COLOR= 4 —set color to dark green 

30 VYLIN 10% 30 AT £0 —drawavertical green line in 
column 20 from row 10 to row 
30 


If you use VL. IN while displaying text instead of graphics, or if part of 
the line being drawn goes beyond row 39 while displaying mixed graph- 
ics and text, Applesoft will display text characters instead of blocks of 
color. For example, if line 1 above were changed to 


LO TEAL —display text instead of graphics 
the result would be a row of flashing D’s and a dollar sign instead of a bar 


of dark green. 


Acolumn coordinate outside the range ® to 35 or a row coordinate out- 
side the range © to 47 will cause the program to halt with the message 


TILLEGAL QUANTITY ERROR 


The VL. IN statement has no visible effect if you use it while displaying 
high-resolution graphics. 





The SCRN Function 


The SCR N (for “screen”) function reads the color currently displayed 
at a designated position on the low-resolution graphics screen. This 
function takes two arguments, the first specifying the column and the 
second the row of the desired position. It yields a number from © to 

i 3 representing the color displayed at that position. For example, the 
expression 


SCRN (3+ 9) 
yields the code for the color displayed at column 5, row 9. 


The SCRN function is not intended for use with high-resolution 
graphics. 
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For Experts Only—Strange Extensions: Although the ordinary limits 
for coordinates on the low-resolution graphics screen are 39 and 47, 
SCRN will actually accept values up to 47 for both arguments. But if the 
column parameter is greater than the usual limit of 39, odd things hap- 
pen. The code yielded by SC FN gives the color for the block whose col- 
umn is the designated column minus 40, and whose row is the 
designated row plus 16. 


If the row-plus-16 number is in the range 4 through 4 7, and if mixed 
graphics and text are being displayed, then the code yielded is not a 
color code, but is related to the text character at that position in the text 
area below the graphics (see “For Experts Only-——-Reading the Text 
Screen,” below). 


If the row-plus-16 number is inthe range 48 toG3, SCRN yields a re- 
sult whose meaning is beyond the ken of mere mortals. 


For Experts Only—Reading the Text Screen: When text is being dis- 
played, SCRN yields numbers in the range © to 1 5 whose value is 
either the high-order four bits (if the row number is odd) or the low-order 
four bits (if the row number is even) of the characterincolumnC + 1 
androw(R + i) / 2,whereC andF are the column and row 
numbers given as arguments to SCRN. Thus the following expression 
will yield the character at position * +‘: 


LHI? 26 Silat 1x 1 
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ss High-Resolution Graphics 
6.2 


There are two separate regions in the Apple Ile’s memory, desig- 
nated page 1 and page 2, that can be used for displaying high-resolu- 
tion graphics. Each consists of 53,760 points (280 columns by 192 
rows), which can be displayed on the screen in 6 colors. This section 
describes the facilities available in Applesoft for using high-resolution 


graphics: 
HGR statement: see Section 6.2.1 e@ The HGR statement instructs Applesoft to begin displaying page 
1 of high-resolution graphics. 
HGR 2 statement: see Section 6.2.2 @ The HGR statement instructs Applesoft to begin displaying 
page 2 of high-resolution graphics. 
HCOLOR = statement: see Section e@ The HCOLOR= statement controls the colors displayed on the 
6.2.3 high-resolution screen. 


HPLOT statement: see Section 6.2.4 @ The HPLOT statement plots individual points and lines on the 
high-resolution screen. 


protecting programs and graphics: section 6.2.5 tells how to protect your programs and high-resolution 
see Section 6.2.5 graphics from overwriting each other in the computer's memory. 
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6.2.1 


HGR displays high-resolution 
graphics page 1 


high-resolution display color: see 
Section 6.2.3 


POKE statement: see Section 7.1.2 


TEXT statement: see Section 5.2.4 


protecting programs and graphics: 
see Section 6.2.5 


A 


The HGR Statement 
HGR 


The HGR (for “high-resolution graphics”) statement instructs Apple- 
soft to display page 1 of high-resolution graphics. If the screen has 
been displaying text, it is changed from 40 (or 80) columns by 24 lines 
of text to 280 columns by 160 rows of high-resolution graphics, with 
space for four lines of text at the bottom. The graphics area of the 
screen is cleared to black; the high-resolution display color is not af- 
fected. HGR doesn't affect the contents of the text screen, the setting 
of the text window, or the location of the text cursor; the cursor will not 
be visible unless it is in one of the bottom four lines of the screen. 


After executing an HGR statement, you can convert the display to full- 
screen graphics (a 280-by-192 grid with no space for text) with the 
statement 


POKE -16302; 0 


This statement will change the bottom four lines of text to high-reso- 
lution graphics. To return to mixed graphics and text, use 


POKE -16301,; 0 


Notice that the first POK E statement above must be executed after 
HGR. If you execute the POKE first, HGR will reset the screen to mixed 
graphics and text. 


The TEAT statement will return to text display with the text window 
set to the full screen and the cursor at the bottom of the screen. To 
turn off high-resolution graphics and return to text display with the 
text window and cursor intact, use the statement 


POKE -16303, 0 


If you intend to use HGR with an Applesoft program longer than about 
6000 (decimal) bytes, see Section 6.2.5 on how to protect your program 
and graphics from overwriting each other. 


Warning 


If you use the reserved word HGF as the first three characters of a vari- 
able name, the HGF statement may be executed before a syntax error is 
detected. For example, executing the statement 


HGRIP = 4 


will unexpectedly turn on high-resolution graphics and may destroy part 
of your program. 
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For more information... 


6.2.2 


HG 2 displays high-resolution 
graphics page 2 


high-resolution display color: see 
Section 6.2.3 


text window: see Section 5.2.4 


TEXT statement: see Section 5.2.4 


POKE statement: see Section 7.1.2 








See Section F.3 for more information on the use of the various text and 
graphics memory pages, and Section H.1 for the memory locations oc- 
cupied by the high-resolution graphics pages. See the Apple /le Refer- 
ence Manual for further technical information on the Apple Ile’s graphics 
display capabilities. 





The HGR2 Statement 
HGR? 


The HGR @ (for “high-resolution graphics, page 2”) statement in- 
structs Applesoft to display page 2 of high-resolution graphics. If the 
screen has been displaying text, it is changed from 40 (or 80) col- 
umns by 24 lines of text to 280 columns by 192 rows of high-resolu- 
tion graphics. The screen is cleared to black; the high-resolution 
display color is not affected. HGR = doesn't affect the contents of the 
text screen, the setting of the text window, or the location of the text 
cursor. 


The TEAT statement will return to text display with the text window 
set to the full screen and the cursor at the bottom of the screen. To 
turn off high-resolution graphics and return to text display with the 
text window and cursor intact, use the statements 


POKE -16300% 0 —switch from page 2 to page 1 
POKE -16303% 0 —switch from graphics to text 


After executing an HGR 2 statement, you can convert the display to 
mixed graphics and text (a 280-by-160 grid with four lines of text at the 
bottom) with the statement 


POKE =-T6301 9-0 


However, when you use this statement while displaying high-resolution 
page 2, the four lines of text will be taken from text page 2 instead of the 
usual page 1. Since Applesoft uses the same memory locations allo- 
cated to text page 2 for program storage, you'll end up displaying gar- 
bage in the bottom four lines of your screen. For this reason, most 
programmers avoid mixing graphics and text when using high-resolution 
page 2. 
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protecting your program: see Section 
6.2.5 


&. 


For more information... 


6.2.3 


HCOLOR = sets high-resolution dis- 
play color 


Table 6-2 Color Codes for High-Resolu- 
tion Graphics 


Code Color 


‘s) black-1 


1 green 


PJ 


violet 
white- 1 


black-2 


mE ww 


orange 


blue 


“Io oO} 


white-2 





If you intend to use HGR = with an Applesoft program longer than about 
14000 (decimal) bytes, see Section 6.2.5 on how to protect your pro- 
gram and graphics from overwriting each other. 


Warning 


If you use the reserved word HGE = as the first four characters of a vari- 
able name, the HGF 2 statement may be executed before a syntax error 
is detected. For example, executing the statement 


HGRZPIELES = 4 


will unexpectedly turn on high-resolution graphics and may destroy part 
of your program. 


See Section F.3 for more information on the use of the various text and 
graphics memory pages, and Section H.1 for the memory locations oc- 
cupied by the high-resolution graphics pages. See the Apple Ile Refer- 
ence Manual for further technical information on the Apple Ile’s graphics 
display capabilities. 





The HCOLOR = Statement 


HCOLOR= 6 
HCOLOR= CJ) 
HCOLOR= (xX - 4) / 8 


The HCOL OR = (for “high-resolution color’) statement sets the dis- 
play color for plotting high-resolution graphics. There are 6 colors 
available, represented by numbers from © to 7, as shown in Table 6-2. 


lf you’re using a monochrome display (black-and-white, or some other 
single phosphor color), the different colors will appear on your screen as 
various patterns of shading. 


The high-resolution display color is not affected by HGR, HGR, or 
FX LIN. Until your program executes an HCOL OR = statement, the 
display color for high-resolution graphics is indeterminate. 


Notice that the equal sign is part of the keyword HCOL OR =; it doesn’t 
represent an assignment to a variable named HCOL OR. A statement 
such as 

LET HCOLOR= x 


will cause a syntax error. The only way to find out the current display 
color is to keep track of it yourself with a separate variable. 
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6.2.4 


HPLOT plots high-resolution points 
and lines 


high-resolution display color: see 
Section 6.2.3 








Curious Behavior: As you wander deeper into the recesses of the Ap- 
ple lle’s graphics system, you'll begin to notice that the colors in high- 
resolution graphics don't always act as you might expect. For example, 
carefully drawn vertical lines may refuse to be visible, a white line cross- 
ing a field of green may leave jagged blocks of orange in its wake, ora 
point plotted with HCOLOR= 3 (white-1) may look blue if its column 
coordinate is even, green if the column coordinate is odd, and white only 
if a point is plotted in the next column as well. These strange phenom- 
ena are a result of the way the Apple Ile’s high-resolution graphics fea- 
tures interact with the color circuitry in your television set. See the Apple 
lle Reference Manual for further explanation. 


If you specify a color code higher than 7, your program will halt with the 
message 


TILLEGAL GUANTITY ERROR 





The HPLOT Statement 


HPLOT 140% 80 

HPLOT X - 16% ¥ + 12 TO A + 16% ¥ - 
le 

HPLOT 70+40 TO 210,40 TG 210s120 TO 
7Qe120 TO 70+40 

HPLOT TQ THETA * 280 / (2ePI)+ 96 - 
(SINCTHETA) * 33) 


The HPL OT (for “high-resolution plot”) statement plots points and 
lines on the high-resolution graphics screen in the current high-reso- 
lution display color. The first expression in each pair specifies a col- 
umn (numbered © to = 79, from left to right); the second expression, 
separated from the first by a comma, designates a row (numbered © 
to 1395 for mixed text and graphics, ® to i191 for full-screen graph- 
ics, from top to bottom). For example, the following program plots a 
white point at column 100, row 50 of the screen: 


10 HGR —display high-resolution 
graphics 

£9 HCOLOR= 3 —set display color to white-1 

30 HPLOT 100; 30 —plot a point at column 100, row 
50 


Figure 6-2 shows the system of coordinates used to designate posi- 
tions on the high-resolution graphics screen. Position © + is the top- 
left corner and position 2 75 + the top-right. When displaying mixed 
graphics and text, the bottom-left corner is position ® +139 andthe 
bottom-right is = 73 +133); in full-screen graphics, the bottom-left 
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corneris O +151 andthe bottom-rightis 279 +191. 


Figure 6-2 Screen Coordinates for High- 
Resolution Graphics 


O, O Lids © 
O, 159 zf7a% iss 
(orO+ 191) (or2 79+ 191) 


To draw aline with HPL.OT, specify the starting and ending points, 
separated by the keyword 1 Q. The next example draws a white line 
across the screen: 


10 HGR —display high-resolution 
graphics 
£09 HCOLOR= 3 —set display color to white-1 


30 HPLOT O+ 830 TO 279+ 30 
—draw aline across row 50 


You can draw a series of connected lines in the same HP LOT state- 
ment by using a series of T 0 clauses. Each line will begin where the 
last one ended. The following program, for example, draws a rectan- 
gle, as illustrated in Figure 6-3: 


10 HGR —display high-resolution 
graphics 
£09 HCOLOR= 3 —set display color to white-1 


3O HPLOT 70;+;40 TQ 210+40 TO 210120 
TO 7O+120 TO 70;+40 
—draw a rectangle 


Figure 6-3 Drawing a Rectangle with 


HPLOT (Starthere:) 70+ 40 210% 40 





7O% 120 21lO, 120 


You can extend the series of lines almost indefinitely within the same 
HPL OT statement, subject only to the limit of 239 characters ina 
program line. 
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HCOLOR = statement: see Section 


6.2.3 


Apple lle memory allocation: see 
Section H.1 








6.2.5 





You can also continue from wherever the last HPL.OT statement 
ended, by writing the keyword T 0 immediately after the word 
HPLOT.For example, adding the line 


40 HPLOT TO 210+ 120 —continue drawing from last 
point 


to the previous program will cause it to draw in the diagonal of the 
rectangle, represented by the dashed line in Figure 6-3. Applesoft 
assumes that the starting point (which ordinarily would have ap- 
peared between the words HPL.QT and TQ) is the last point plotted. 


The color of the new line drawn by HPLOT TOisthe same as that of 
the last point plotted. Even if you insertanew HCOLOKR = statement 
between lines 30 and 46, the linedrawn bythe HPLOT TO inpro- 
gram line 4 will appear in the same color as those drawn in line 30. 


To change the color of the line, use awhole new HPLOT: 


go HLCULOR= 6 —change color to blue 


QO HPLO? 70+. 40 10 230: 120 
— continue drawing from last 
point 


If the screen is displaying mixed text and graphics, an attempt to plot a 
point whose row coordinate is in the range 160 to 191 will have no vis- 
ible effect. However, if you draw a line either beginning or ending in rows 
160 to 191, Applesoft will display as much of the line as it can. If you later 
switch to full-screen graphics with POKE -16302 +0 the hidden por- 
tion of the line will appear. 


Warning 


Be sure to precede HPL.OT by either HGR or HGR = or you will write 
over lots of memory, including your program and variables. 





If the column coordinate given to HPL.OT is outside the range © to 
< 7%, or the row coordinate outside the range ® to 141, the program 
will halt with the message 


TILLEGAL GUANTITY ERROR 





Protecting High-Resolution Graphics 


The two high-resolution graphics pages lie pretty much in the center 
of things: page 1 resides at memory addresses 8152 to 16383 

(hexadecimal $2000 to $3F FF) andpage 2 ataddresses 16384 
to 24373 (hexadecimal #4000 to $3F FF). Because Applesoft 
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HGR statement: see Section 6.2.1 


HIMEM: statement: see Section 7.2.1 


HGR 2 statement: see Section 6.2.2 


POKE statement: see Section 7.1.2 





program storage begins at location 2048 (hexadecimal $80), it’s 
easy for your program and graphics to get in each other’s way. For 
example, if you're using the HGR statement to display page 1 of high- 
resolution graphics, you have only 6144 bytes of program and vari- 
able space (8152 minus 2048) before your program overwrites 
the graphics area. This section tells how to prevent them from collid- 
ing, causing untold mayhem and destruction. 


One way to protect your program and graphics from each other is to 
use the H I MEM: statement to set the upper limit of program memory 
at 8 i152. This is areasonable method to use for short programs; but 
Applesoft tends to use a lot of memory, and longer programs would 
soon run out of space. 


Another method that allows the program a bit more breathing room is 
to use the second page of graphics instead of the first (HGR 2 instead 
of HGR). This has the benefit of starting the graphics at a higher 
memory location, so you can set HI MEM: to 16384 instead of 
8192, allowing 14336 bytes (16384 minus 2048) for your pro- 
gram and variable space. The disadvantage of this method is that you 
lose the four lines of text at the bottom of the screen, which are avail- 
able with HGR but not with HGR 2. 


A third method, probably the best for long programs with lots of vari- 
ables, is to use the wizardry of the POKE statement to change the 
start, instead of the end, of Applesoft’s program storage space. The 
following statements will start program and variable storage above 
graphics page 1, beginning at address 16384 (hexadecimal 
$4000): 


PORE 104% 1 
POKE 104, 64 
POKE 16384; 0 


These statements will start program and variable storage above 
high-resolution page 2, beginning at address 24376 (hexadecimal 
$5000): 


PURE 10g? I 


POKE 104, 96 
PORE 24376+ 0 
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NE command: see Section 1.2.1 


fy UN command: see Section 1.2.4 


6.3 


6.3.1 


shape table: a collection of one or more 
shape definitions, together with their 
indices 


plotting vector: a code representing a 
single step in drawing a shape on the 
screen 





No matter where you start program space in memory, your next com- © 
mand should be 


NEW 


to clear out any old variables and system control information so you 
can start a fresh program beginning at the new location. (If your com- 
puter is equipped with one or more disk drives, you can accomplish 
the same thing by loading a new program from a disk with the RUN 
command.) 


Shape Tables 


Applesoft has a number of special facilities that allow you to manipu- 
late shape tables defining shapes on the high-resolution graphics 
screen. Because shape tables have the advantages of both flexible 
design and very fast execution, they are ideal for applications such as 
on-screen animation. This section contains detailed information on 
creating and manipulating shape tables. 


For Hackers Only: Since the advent of the Apple II series of computers, 
a number of excellent graphics software packages have appeared on 
the market. Available at most computer stores, these packages take the 
hard-core technical work (binary arithmetic and machine-language ma- 
nipulation) out of designing and using shape tables. The information in 
this section is intended for those programmers who enjoy “twiddling the 
bits” themselves. 


To use this section effectively, you'll need to Know about bits and bytes 
and the rudiments of hexadecimal arithmetic. This information is avail- 
able in any basic text on computer science; see the bibliography in the 
Apple Ile Owner’s Manual that came with your computer. All computer 
memory addresses in this section are in hexadecimal; all other num- 
bers, unless otherwise noted, are in decimal. 





Creating a Shape Table 


An Applesoft shape definition consists of a sequence of plotting vec- 
tors that are stored in a series of consecutive bytes in the computer's 
memory. One or more such shape definitions, with their indices (see 
“The Shape Table Index,” below), make up a shape table. 


Plotting Vectors 


Each byte in a shape definition has three sections. Each section may 
contain a plotting vector, specifying whether to plot a point at the cur- 
rent screen position and in what direction to move (up, down, left, or 
right) before processing the next vector. Thus each byte can repre- 
sent up to three plotting vectors. 
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Figure 6-4 Plotting Vectors in a Byte 


section: 


bit number: 


specifies: 


If DD OO 
Ol 
10 
Ld 


IfP = 9 


DRAW and * 
Section 6.3.2 


C B A 
te 


763 432 1 9 


vor DO FD B 


move up 
move right 
move down 
move left 


don't plot 
plot a point 


DRAW statements: see 


Figure 6-5 Plotting a Shape 





Figure 6-4 shows how the three sections are arranged within each of 
the bytes that make up a shape definition. In each plotting vector, bit 
P specifies whether to plot a point before moving, and the pair of bits 
designated DD specify the direction in which to move before pro- 
cessing the next vector. 


Notice that the last section in each byte (the two high-order bits, la- 
beled C in the figure) does not include a P bit. The value of P in such 
a section is always assumed to be © (don’t plot); thus section C can 
only specify a move without plotting. 


How Plotting Vectors Are Interpreted 


The DRAW and ADR AK statements read through each byte in the 
shape definition, from the first byte in the definition to the last. Within 
each byte, the sections are processed from right to left: section A, 
then B, then C. When a byte is encountered that contains all zeros, 
the shape definition is complete. 


At any section in the byte, if all the remaining sections contain only 
zeros, then those sections are ignored. Thus a byte can't end with a 
move in section C of 20 (move up without plotting), because that 
section, containing only zeros, will be ignored. Similarly, if section C 
is 0 (ignored), then section B cannot be a move of 0 O(move up 
without plotting), since that will also be ignored. And a vector of O00 
in section A will end your shape definition unless there is a one bit 


somewhere in section B or C. 


Coding a Shape Table 


Suppose you want to draw a shape like that shown in Figure 6-5a. To 
convert the shape into an Applesoft shape definition, follow these 
steps: 


1. Draw the shape on graph paper, one dot per square. 


2. Decide where to start drawing the shape—let’s start this one at 
the center—and draw a path through each point in the shape, us- 
ing only 90-degree angles on the turns, as in Figure 6-5b. 


3. Redraw the shape as a series of plotting vectors, each vector 
moving one place up, down, left, or right, and distinguish those 
vectors that plot a point before moving. This step is illustrated in 
Figure 6-5c; vectors that plot before moving are marked in the 
figure with a dot at the beginning of the direction arrow. 
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4. “Unwrap” the vectors and write them out in sequential order, as 
in Figure 6-5d. 


Figure 6-5 continued d 


ry EEE 


Now you're ready to code the plotting vectors as a shape definition 
table. Figure 6-6 gives the binary codes corresponding to each pos- 
sible vector. For each vector in the shape, determine the proper bit 
code and place it in the next available section in the table, as shown 
in Figure 6-7. If the code won't fit (for instance, the vector in section C 


can't plot a point) oris a OO (or 000) at the end of a byte, then just fill 
that section with zeros. 


errs oe 


Figure 6-6 Codes for Plotting Vectors 


vector code 


move 
only 


plot 
and move 





Figure 6-7 Shape Definition Table 





; C B A 
section 
byte 4 | | O10 
1 —- < a1] 
ra } T O00 
JI| > i i 100 
4 - - 101 
5 { o> 101 
6 i t 110 
7 = 110 
8 < 11] 
J O00 |«— denotes end 
of shape 
an this vector __ 4 definition 
cannot plot 
or move up 
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Binary 


Ood00 
ereren! 
QOoO10 
QOO1il 
O100 
O1o01 
QO110 
O11] 
1000 
1001] 
1010 
1011 
1100 
1101 
1110 
Lidd 


Table 6-3 Hexadecimal Byte Codes 


Hex 


~, 
te 
al 


foots 


fr 


my EE Ww 


1 mon woe Pp wo OO NS OF 


Figure 6-8 Converting the Shape Defini- 
tion to Hexadecimal 





The final step is to convert the binary codes representing the plotting 
vectors into hexadecimal form so you can type them into the com- 
puter. As shown in Table 6-3, each hexadecimal code corresponds to 
a group of four bits; so each row of eight bits in your definition table is 
represented by two such codes (called hexadecimal digits). This step 
is illustrated in Figure 6-8. The final shape definition for the shape in 
Figure 6-5 is 


i2 SF 20 64 2D 15 36 1E OF7 OO 


The Shape Table Index 


There is still a little more information you need to provide before you 
have a complete shape table: the table must have an index. This is 
simply a list indicating where in memory to find a particular shape. 
Applesoft needs the index so that it can find the shape later, when 
your program tries to draw the shape on the screen. 


bytes 
Section: C B A peri 
EPS a 
byte O O001 9010 = 12 
7 OGL TLiiil = sr 
7 OO1L10 0000 = 20 
3 @©110 60100 = 64 
“O0Lto 11Ggil = 2G 
- OO OL1as = is 
G6 @0116061160 = S6 
@ GO©OOL LTiio = LE 
8 O000 O111 = QF 
9 O0O00 0000 = 00 <denotesend 
yet ag of shape 
hex: — digit 1 digit 2 definition 


The form of a complete shape table, including the index, is shown in 
Figure 6-9. The shape table’s starting location, whose address is 
called 5 in the figure, contains the number of shape definitions in the 
table (between © and FF) in hexadecimal. The next byte (address 
5S +  1)is unused; it is followed by a sequence of two-byte pairs 
giving the locations of the shapes in the table. (Notice that the shape 
locations are given with the bytes reversed—low-order byte first— 
and that the locations are specified relative to address 5, the start of 
the table itself, and not in absolute memory addresses.) For simplic- 
ity, the shape definitions themselves are usually placed immediately 
after the index. 
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Figure 6-9 Form of a Complete Shape 
Table 


Figure 6-10 A Complete Shape Table 
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high-resolution graphics pages: see 
Sections 6.2.1, 6.2.2 
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shape definition #1 





first byte 
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shape definition #2 
shape ° 
definitions P 






shape definition #n 





Figure 6-10 shows the complete shape table for our example. Since 
there’s only one shape in the table, location S contains the value i. 
BytesS + e#andS + 3areneeded to specify the shape’s lo- 
cation; the shape definition itself can start in the next available byte, 5 
+ 4.SoindexbyteS + contains the value ©4 and index byte 
S + 3contains the value 00. Next come the bytes of the shape 
definition, as derived in Figure 6-8. The table ends with the zero byte 
marking the end of the shape definition. 


Loading a Shape Table into Memory 


Now that you've figured out how to code your shape in the form of a 
shape table, you have to get it into the computer's memory so Apple- 
soft can draw it on the screen. You also have to tell Applesoft where 
in memory to look for the shape table. 


First you must choose a starting address. This address must be less 
than the highest memory address available in your system, and must 
not be located in the high-resolution graphics page that you'll be us- 
ing to display the shapes (locations £000 through 3F FF for page 1, 
4000 through SF FF for page 2). For this example, we'll use hexa- 
decimal address 1 DFC, which is just below high-resolution page 1. 


Graphics 





A 


Keep shape table out of harm's way 


Apple lle Monitor program: see Apple 
lle Reference Manual 


Dik Al statement: see Section 6.3.2 


POKE statement: see Section 7.1.2 


Warning 


Be sure you don’t place your shape table in an area that will conflict with 
your program or variable space, or with vital internal information used by 
the system. See the box labeled “Protecting Your Shape Table,” below, 
for information on how to keep your program and shape table out of each 
other’s way; see Appendix H for the memory locations of important sys- 
tem information. 





While you're in the process of creating the shape table, you'll proba- 
bly want to type the table into memory directly from the keyboard us- 
ing the Monitor program. Then you can draw the shape on the screen 
with an immediate-execution Dkk Ald statement, see if it looks the way 
you want it, and go back and change it if it doesn’t. See your Apple Ile 
Reference Manual for information on the use of the Monitor program. 


Once your shape table looks correct, you'll want to be able to use it 
from within a program. Your program can store the table into memory 
by using POKE. To do this, you have to convert the starting address 
of the table, and each byte of the table itself, from hexadecimal to 
decimal, then store the decimal values into memory one at atime. 


The shape table we’ve been developing consists of the hexadecimal 
bytes 


O1 00 04 00 12 3F 20 G4 2D 15 36 1E O07 
Oo 


The equivalent decimal values are 
1040 18 GS 32 100 45 21 34 30 / U 


The starting address we’ve chosen for the table, hexadecimal 1 DFC, 
is equivalent to 7G 76 decimal. So the following statements in a pro- 
gram will store the shape table into memory: 


10 FOR «x = 7676 to 7689 
—memory locations where 
shape table will go 


20 READ A —read byte of table 
30 POKE Ke A —store at next location 
40 NEXT A —go back for next byte 
20 DATA 1:°0+94:+0+18+63+32+100 +4321 
94 +30+7 +0 —contents of table 
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Store the starting address of the shape 
table 


SHLOAD statement: see Section 6.3.2 


Protect your tables 


HIMEM: statement: see Section 7.2.1 








Another way for a program to store a shape table into memory is to load 
it from a disk or tape cassette. Details are given below under “Saving 
and Loading a Shape Table.” 


Now that you have your shape table in memory, you have to tell 
Applesoft where to find it. Applesoft looks for the table’s starting ad- 
dress in hexadecimal locations E 8 (low-order byte) and E 3 (high-or- 
der byte), so you have to arrange somehow to store the correct 
starting address into these locations. If you’ve been using the Monitor 
program to type the shape table into memory from the keyboard, you 
can type its address into locations E8 and E 9 in the same way. From 
within a program, you can do it with two more POQKE statements. The 
hexadecimal addresses E8 and ES) are equivalent to decimal 232 
and = .3.3; the two bytes of the table’s starting address, 1D and FC, 
are equivalent to 29 and £32. So the following POKE statements 
will do the trick: 


BO FURE 20cr coe * PUKE 2aa* 2a 


Your shape table is now stored correctly in the computer's memory, 
ready to be drawn on the screen from within your program with a 
DRAW statement. 


Remember to store the two bytes of the starting address in reverse or- 
der, with the low-order byte before the high-order byte. This convention 
is always followed when storing memory addresses in the Apple lle’s 
memory. 


When you use SHL. OAD to load a shape table from a tape cassette, the 
starting address is set up for you automatically in the proper locations. 


Protecting Your Shape Table: In choosing a location in memory for 
your shape table, it’s important to keep it out of the way of your Applesoft 
program, so the two don't overwrite each other. One way to do this is 
simply to use HI MEM: to set the upper limit of program memory to the 
starting address of the table. In the example, 


Maes 7676 


This too is done automatically when you use SHL. OAD to get the table 
from a tape cassette. 


Unfortunately, this method leaves very little room for your program and 


variables—in the example, only 5628 bytes (76 76 minus 2048). You 
can buy alittle more space for your program by setting HIMEM: tothe 


Graphics 


Don’t overwrite DOS! A 


Saving a shape table on a disk 


DOS: Disk Operating System 


BSAVE command: see DOS manual 


binary file: a file containing “raw” infor- 
mation not expressed in text form 





beginning of the graphics page you’re using (8192 forpage 1, 16384 
for page 2), as suggested in Section 6.2.5, “Protecting High-Resolution 
Graphics.” You can then locate the shape table above the graphics 
page: that is, above location 16384 if you’re using page 1, 243 76 if 
you re using page 2. 


Perhaps the best method is to locate the program and variables above 
the graphics page, again as described in Section 6.2.5. This leaves 
room for the shape table below the start of the graphics page. If you’re 
using graphics page 1, that’s 6144 bytes (81 92 minus 2048)— 
enough room for a very extensive shape table! 





Warning 


lf you locate your shape table above the high-resolution graphics page 
and your system is equipped with one or more disk drives, be careful not 
to run into the memory space occupied by the Disk Operating System, 
beginning at location 38400 (hexadecimal 9600). 





Saving and Loading a Shape Table 


To save your shape table on a disk, you need to know two things: 


@ Thestarting address of the table (1 DFC in the example) 
@ The length of the table in bytes (14 in the example—hexadecimal 
© 00E—including the “stop” byte) 


Next, you must choose a file name under which to store your shape 
table on the disk. We'll use SHAPE I for this example. 


To save the table on a disk in immediate execution, put the disk in the 
disk drive and issue the following DOS command: 


BSAVE SHAPEL+ ASIDFC, LSO00E 


This command says “store a binary file named SHAPE 1 onthe disk, 
containing the current contents of memory starting at hexadecimal 
address 1DFC, and OO0E (hexadecimal) bytes long.” 


lf you’re using a disk drive other than the main startup drive, the BSAVE 
command should also include slot and drive parameters specifying 
which disk drive to use; see your DOS manual for details. 


To issue the same command from within an Applesoft program, use 
the statement 


PRINT CHRS (4)5 "BSAVE SHAPEL+ ASIDFC, 
LSQOOE" 
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Loading a shape table from a disk 


BLOAD command: see DOS manual 


Don't forget the starting address 


Saving a shape table on tape 


Apple lle Monitor program: see Apple 
lle Reference Manual 


Loading a shape table from tape 


SHLOAD statement: see Section 6.3.2 








Again, see your DOS manual for details. 


To load the table back into memory from the disk, you can use the 
DOS command 


BLOAD SHAPE] 
in immediate execution, or the statement 
PRINT CHR (4)5 "BLOAD SHAPEI" 


from within a program. Notice that you don’t have to include the start- 
ing address and the table length; this information will be picked up 
automatically from within the disk file itself. However, the starting ad- 
dress is not stored automatically into the special addresses where 
Applesoft looks for them, so you (or your program) will have to do that 
for yourself: 


PORE 294% 202 $€ PUAE 2554 25 


To save your shape table on a tape cassette, you need to know three 
things: 


@ Thestarting address ofthe table (1 DFC inthe example) 
@ The last address ofthe table (1E 09 in the example) 


@ The difference between the first two items (hexadecimal! OO0D, 
decimal 14) 


ltem 3, the difference between the last address and the first address 
of the table, must be stored in locations © (low-order byte) and 1 
(high-order byte). From the Monitor, type 


O:OoD oOo 


and press | RETURN |. Now you must write to the cassette first the ta- 
ble length from locations © to i, then the shape table itself: 


O.,ilW iDFC.1EOSW 


Don’t press the key until you’ve put a cassette in your tape re- 
corder, rewound it, and started it recording. 


To load the shape table back from the tape, use the SHLOAD 
statement. 
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[ CONTROL |-C: see Section 1.3.2 


6.3.2 


Using Shape Tables 


The commands in this section are used to draw and manipulate on 
the screen shapes defined by a shape table in memory: 


@ DRAW and XDRAW draw shapes froma shape table onto the 
high-resolution screen. 


@e SCALE = controls the scale at which shapes are drawn on the 
screen. 


@ QT = controls the rotation of shapes on the screen. 


@® SHLOAD loads ashape table into memory from a tape cassette. 


As a preview of what the commands in this section can do, here’s a 
sample Applesoft program for you to try. The program first stores into 
memory the shape table developed in Section 6.3.1, using the POKE 
statement (see “Loading a Shape Table into Memory).” Then it uses 
the statements described in this section to produce a somewhat sur- 
prising effect on the screen. See if you can guess what the program 
will display, then type it and run it: 


10 FOR KX = 7676 TO 7689 
—memory locations where 
shape table will go 


£09 READ A —read byte of table 
30 POKE A: A —store at next location 
4Q NEAT «A —go back for next byte 
20 DATA 1°0+4+0;18;63+32+;100;,45;,21,; 
244309740 —contents of table 
100 HGRe 


110 HCOLOR= 3 

120 FOR R = 1 TO 50 
igO KUT= FR 

i140 SCALE= R 

130 ADRAW 1 AT 140, 96 
iGO NEXT R 

170 GOTO i120 


When you get tired of watching the show, interrupt the program by 
pressing -C to regain control of the system. 
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Di All draws a shape on the high- 
resolution screen 


shape tables: see Section 6.3.1 


HCOLOR = statement: see Section 
6.2.3 





A 





The DRAW Statement 


DRAW 3 

DRAW 1 AT 140; 36 

DRAW SHAPE AT KACENTER + AOQFFSET + 
TEENTER + YTOrPPSET 


The DRAW statement draws a shape from a shape table on the high- 
resolution graphics screen at a specified location. The expression 
following the keyword DF Al gives the index number of the desired 
shape within the shape table currently in memory. The location at 
which the shape is to be drawn is specified by a pair of expressions 
following the keyword AT, separated by acomma. The first expres- 
sion gives the horizontal screen position of the shape’s starting point; 
the second gives the vertical position. 


The designated shape is drawn in the current display color, scale, 
and rotation, as specified in the most recently executed HCOLOR =, 
SCALE =,andkOQT = statements. 


Warning 


You must specify the color, scale, and rotation of the shape before 

Dik AWW is executed. If any of these have not been specified, the results 
will be random: odd dots may appear, bizarre shapes may be drawn, 
and memory may be overwritten. 


Assuming that a shape table is already loaded into memory (see 
“Loading a Shape Table into Memory” in Section 6.3.1), the following 
program will draw the first shape in the table at column 50, row 100: 


10 HGR — display high-resolution 
graphics 

£9 HCOLOR= 3 —set color to white-1 

30 ROT= 0 —orient shape as originally 
defined 

40 SCALE= 3 —enlarge shape 5 times 

20 DRAW 1 AT 30+ 100 —drawshape1 atcolumn 50, 
row 100 


If you omit the Keyword AT and the screen coordinates, 


20 DRAW 1 


Graphics 


HPLOT statement: see Section 6.2.4 


~DRAW statement: see below 


Be sure to load a shape table first A 


CONTROL |-| RESET |: see Section 1.3.2 


HG statement: see Section 6.2.1 


XDRAM erases a shape 


Complementary colors 





Applesoft will put the shape on the screen starting at the last point 
plotted by the most recently executed HPLOT, DRAW, or DRAW 
statement. (The shape drawn on the screen may not actually begin at 
the last point previously plotted. If the first plotting vector in the shape 
doesn’t actually plot a point, there will be an offset between the first 
visible point in the shape and the last point plotted.) If no such state- 
ment has been executed, the results are unpredictable. 


If the shape number specified is less than © or greater than the actual 
number of shapes in the shape table, the program will halt with the 
message 


VILLEGAL QUANTITY ERROR 





Warning 


If you execute DF AW without first loading a shape table into memory, the 


system may hang (use[ coNnTROL |-[ RESET | to recover), or Applesoft 
may draw random shapes anywhere in the high-resolution graphics 


area of memory (locations 81 92 to £43 73 decimal), whether or not 
HGR or HGR 2 has previously been executed. This can have disastrous 
consequences if your program is longer than about 6000 bytes. 


The XDRAW Statement 


ADRAW 3 

ADRAW 1 AT 140% 80 | 

XDRAW SHAPE AT XACENTER + XOFFSET: 
YOENTER + TORPFSET 


The XDRAk statement works exactly the same as DRAW, except 
that the color used to draw the shape is the complement of the color 
already existing at each point plotted. The following pairs of colors 
are complements: 

@ black and white 

@ violet and green 

@ blue and orange 

DRA is most commonly used to erase a previously drawn shape. 


The following program, which assumes that a shape table has al- 
ready been loaded into memory (see “Loading a Shape Table into 
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Be sure to load a shape table first A 


CONTROL |-|RESET| : see Section 1.3.2 


HG statement: see Section 6.2.1 








Memory” in Section 6.3.1), illustrates the point by drawing and then 
erasing the same shape, leaving the screen blank: 


10 HGRe —display full-screen high-reso- 
lution graphics 

£0 HCOLOR= 3 —set color to white-1 

30 ROT= 0 —orient shape as originally 
defined 

40 SCALE= 3 —enlarge shape 5 times 

20 DRAW 1 AT 30+ 100 —drawshapeatcolumn 150, 
row 100 


G60 FOR 2 = 1 TQ 800 : NEXT 2 
—Sstall for a short time 
70 KDRAW I AT 30+ 100—erasetheshape 


If you use DRAW and XDRAW alternately in a loop, you can do 
animation: 


10 HGR2 —display full-screen high-resolu- 
tion graphics 

20 BLOULOR= 4 —set color to white-1 

30 ROT= 0 —orient shape as originally 
defined 

40 SLALE= © —enlarge shape 5 times 

oO POR A oe TO 2eo —loop 200 times 


60 DRAW 1 AT 30 + Ky 100 
—draw shape in a different col- 
umn each time 
70 KDRAW 1 AT 30 4+ Ks 100 
— erase shape 
SO NEKT xX —repeat loop 


If the shape number specified is less than © or greater than the actual 
number of shapes in the shape table, the program will halt with the 
message 


TILLEGAL QUANTITY ERROR 


Warning 
If you execute ADR AW without first loading a shape table into memory, 


the system may hang (use [ conTROL |- to recover), or Applesoft 
may draw random shapes anywhere in the high-resolution graphics 
area of memory (locations 8192 to 243 73 decimal), whether or not 
HGR or HGR = has previously been executed. This can have disastrous 
consequences if your program is longer than about 6000 bytes. 


Graphics 


SCALE = sets scale factor for DRAW 
and KDRAW 


DRAW and XDRAW statements: see 
above 





The SCALE = Statement 


SCALE= 10 
SCALE= 2 / 4 


The SCALE = statement sets the scale factor (relative size) for the 
high-resolution graphics shape to be drawn by DRAW or ADRAW. 
The expression following the keyword SCALE = specifies the scale 
factor, which may range from i (reproduce the shape exactly as orig- 
inally defined) up to a maximum of #35 (draw the shape 255 times 
the size originally defined). 


Assuming that a shape table is already loaded into memory (see 
“Loading a Shape Table into Memory” in Section 6.3.1), the following 
program will draw the first shape in the table at three different posi- 
tions on the screen and in three different sizes: 


10 HGRe —display full-screen high-reso- 
lution graphics 

£0 HCOLOR= 3 —set color to white-1 

30 ROT= —orient shape as defined 

40 SCALE= i —use original size 

20 DRAW 1 AT 100+ 100—drawshapeatcolumn 100, 
row 100 

GO SCALE= @ —scale to twice original size 

70 DRAW 1 AT 130+ 100—drawatcolumn 150, row 100 

80 SCALE= 3 —scale to three times size 

90 DRAW 1 AT 200+ 100—drawatcolumn 200, row 100 


Ascale setting of ® is considered equivalent to the maximum setting 
(235). If the scale setting specified is less than © or greater than 255, the 
program will halt with the message 


PILLEGAL QUANTITY ERROR 


Scale factors are useful only up to a certain point. Large scale settings 
produce some rather outlandish results on the screen. 


Notice that the equal sign is part of the keyword SCALE =; it doesn't 
represent an assignment to a variable named SCALE. Astatement 
such as 

LEl SUALE— A 


will cause a syntax error. The only way to find out the current scale 
setting is to keep track of it yourself with a separate variable. 
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OT = sets rotation for DR AW and 
xDRAW 


DRAW and XDRAW statements: see 
above 


Rotation also depends on scale 
setting 


scale setting: see above 








The ROT = Statement 


ROT= 16 
ROT= 32 4+ £ * R 


The ROT = (for “rotation’) statement sets the angular rotation for the 
high-resolution graphics shape to be drawn by DRAW or KDRAW. 
The expression following the keyword 0 T = specifies the rotation 
in units of 5.625 degrees (1/64 of acircle). ROT = © willorientthe 
shape exactly as defined inthe shape table, FOT= 16 willrotate 
the shape 90 degrees clockwise, FOT= 32 will rotate it 180 de- 
grees, and soon. The process repeats starting atROT= 654. 


Assuming that a shape table is already loaded into memory (see 
“Loading a Shape Table into Memory” in Section 6.3.1), the following 
program will draw the first shape in the table, five times its original 
size, at two different positions on the screen, once oriented as origi- 
nally defined and once rotated by 45 degrees: 


10 HGR2 —Display full-screen high-reso- 
lution graphics 

£9 HCOLOR= 3 —set color to white-1 

30 SCALE= 3 —scale shape to five times origi- 
nal size 

40 ROT= 0 —orient shape as originally 
defined 

20 DRAW 1 AT 30+ 100 —drawshape atcolumn 50, row 
100 

G0 ROT= 8 —rotate shape 45 degrees 

70 DRAW 1 AT 100% 100—drawshape atcolumn 100, 
row 100 


The amount of rotation obtainable is somewhat dependent on the 
current scale setting. ForSCALE= i, Applesoft recognizes only 
four rotation values (0,16, 32,48);forSCALE= @, itrecognizes 
eight rotation values (0,8,16,...);forSCALE= 3, itrecognizes 
twelve rotation values; and so on. For scale settings of 1 G or more, 
the full range of rotation values is available. For unrecognized rota- 
tion values, Applesoft usually orients the shape with the next smallest 
rotation that it recognizes. 


Graphics 


SHL OAD loads a shape table from 
tape 


HIMEM: statement: see Section 7.2.1 





Notice that the equal sign is part of the keyword ROT =; it doesn’t repre- 
sent an assignment to a variable named ROT. A statement such as 


LET ROT= X 


will cause a syntax error. The only way to find out the current rotation 
setting is to keep track of it yourself with a separate variable. 


If the rotation setting specified is less than © or greater than 235, the 
program will halt with the message 


PILLEGAL QUANTITY ERROR 


The SHLOAD Statement 
SHLOAD 


The SHL.OAD statement (for “shape load”) loads a shape table from 
a tape cassette. The shape table is loaded just below the upper limit 
of available program and variable space (HIMEM:);HIMEMs is 
then set just below the shape table to protect it. 


To use SHL. OAD in immediate execution, turn on your tape recorder 
with the proper tape inserted and cued up to the proper place. Then 
type 


SHLOAD 


and press . You should hear one “beep” when the shape 
table’s length has been read successfully, and another when the ta- 
ble itself has been read. 


You can also use SHL. OAD from within a program (with appropriate 
prompting messages) to allow users to load their own shape tables: 


100 PRINT "CUE UP YOUR SHAPE TAPE AND 
PRESS THE PLAY BUTTON." 
110 PRINT "THEN PRESS THE RETURN KEY TO 
LOAD THE SHAPE TABLE," 
—prompt user with instructions 
iZO GET STALLS —wait for keypress 
130 SHLOAD —load shape table from tape 
140 PRINT "TABLE LOADED—PLEASE SHUT OFF 
YOUR RECORDER. “ —tell user table is loaded 
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Don't forget to turn on your tape recorder! 


CONTROL |-|RESET| : see Section 1.3.2 


For more information... 





If you load a second shape table replacing the first one, you or your pro- 
gram should reset HI MEM: to avoid wasting memory. See the section 
“Loading a Shape Table into Memory” in Section 6.3.1 for more informa- 
tion on shape tables and memory usage. 


If you try to use SHL. OAD without a tape recorder connected, 
turned on, and set to play, the system will hang indefinitely. Use 


[CONTROL |-[ RESET | to regain control. 


If a variable name begins with the reserved word SHL.OAD 
SHLOADER = 39 


5 HL OAD may be executed before a syntax error is detected. In sucha 
case, the system will patiently wait (forever, if necessary) for a shape ta- 


ble to be loaded from a tape cassette. Again, use [ conTRoL |-{ RESET | to 


recover. 


For information on saving a shape table on tape, see “Saving and Load- 
ing a Shape Table” in Section 6.3.1. See Appendix M for a list of all 
statements dealing with tape cassettes. 
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7.2 


7.3 


System Utilities 

7.1.1 The PEEK Function 

7.1.2 The POKE Statement 
7.1.3 TheCALL Statement 
7.1.4 The US Function 

7.1.5 TheWAIT Statement 
Memory Management 

7.2.1 TheHIMEM: Statement 
7.2.2 TheLOMEM: Statement 
7.2.3 The FRE Function 
Debugging Facilities 

7.3.1 The TRACE Command 
7.3.2 The NOTRACE Command 











direct memory access: see Section 7.1 


memory management: see Section 7.2 


debugging: see Section 7.3 


Utility Statements 


The features covered in this chapter are concerned with low-level 
control of the programming environment. 


Section 7.1, “System Utilities,” discusses direct access to specific lo- 
cations in the computer’s memory from within an Applesoft program. 


Section 7.2, “Memory Management,’ describes the ways in which 
Applesoft programs can control the limits of program space. 


Section 7.3, “Debugging,” tells how to trace the execution of a run- 
ning program for debugging purposes. 


System Utilities 
71 


PEEK function: see Section 7.1.1 
POKE statement: see Section 7.1.2 
CALL statement: see Section 7.1.3 
US function: see Section 7.1.4 


WAIT statement: see Section 7.1.5 


This section describes statements and functions that give Applesoft 
programs direct access to the Apple Ile’s memory: 


@ PEEK examines the contents of amemory location. 


@ POKE alters the contents of amemory location. 


CALL and USK allow Applesoft programs to execute machine- 
language subroutines stored in the computer's memory. 


lA I T suspends program execution until a specified signal is 
received from a peripheral device. 


System Utilities 








7.1.1 


PEEK examines contents of a mem- 
ory location 


Certain locations hold special informa- 
tion or produce special effects: see 
Appendix F 


POKE alters contents of a memory 
location 


170 


The PEEK Function 


The PEEK function directly examines the contents of a specified lo- 
cation in the computers memory. The argument given to PEEK is the 
decimal address of the desired memory location. PEEK yields the 
contents of the specified location, which will be an integer from © to 
=<... FOr example, the following program displays the contents of 
addresses 100 through 120: 


10 FOR ADDR = 100 
TO 120 —loop through desired 
addresses 
£09 PRINT "LOCATION “5s ADDR: "HOLDS THE 
VALUE “5s PEEK (ADDR) 30 NEAT ADDR 
—display contents of location 
—go back for next address 


Certain locations in the Apple Ile’s memory hold special system infor- 
mation or produce special effects whenever their contents are read. 
One important use of PEEK is for manipulating these special loca- 
tions. See Appendix F, “Peeks, Pokes, and Calls,” for details. 


lf PEEK is given a negative argument value, itadds 63336 (2 to the 
16th power) to obtain an equivalent positive address. For example, 


PEEK (-16384) isequivalentto PEEK (49152 

PEER 4-1) isequivalentto PEEK (635333) 
PEEK (-32768) isequivalentto PEEK (32768) 
PEEK (-63300) isequivalentto PEEK (36) 


If the argument is notin the range -G5335 to + 63535 »+ the pro- 
gram will halt with the message 


TILLEGAL QUANTITY ERROR 





The POKE Statement 


POKE 34; 8 
POKE -16302% 0 
POKE ADDR, (2*D1 + 3*D2) / (U - VY) 


The POKE statement stores a specified value directly into a location 
in the computer's memory. The first expression following the keyword 
POKE gives the decimal address of the memory location; the second 


Utility Statements 


A 


CONTROL |-| RESET |: see Section 1.3.2 


CALL executes a machine-language 
subroutine 





expression, separated from the first by a comma, gives the value to 
be stored into that location. For example, 


POKE 34; 8 —stores value 8 into location 
34 


Warning 


Be certain that the address into which you are storing doesn’t contain 
part of your program or some vital system information that you don't 
want to change. An ill-advised POK E can hang the system, drop you 
into the Monitor, or alter the operation of the system or of your program in 
unpredictable and possibly disastrous ways. In the event of catastrophe, 


use -[ RESET |to regain control of the system. See Appendix 
H for the locations of vital system information that shouldn't be tampered 
with. 


Certain locations in the Apple Ile’s memory hold special system infor- 
mation or produce special effects whenever a value is stored into 
them. One important use of POKE is for manipulating these special 
locations. See Appendix F, “Peeks, Pokes, and Calls,” for details. 


If POKE is given a negative target address, itadds 63336 (2 tothe 
16th power) to obtain an equivalent positive address. For example, 


POKE -16538d; 0 isequivalentto POKE 491323 0 
POKE -32768, 112 isequivalentto POKE 32768, 
liz 


POKE -655302+ 8 isequivalentto POKE 34, 8 

If the target address is not inthe range -G3535 to + 63335, orifthe 
specified value is notin the range © to 255, the program will halt with 
the message 


VILLEGAL QUANTITY ERROR 





The CALL Statement 


CALL 34915 
CALL -936 
CALL ROUTINE (J) 


The CALL statement executes a machine-language subroutine from 
within an Applesoft program. The decimal address of the desired 
subroutine follows the keyword CALL. Control is transferred to the 


System Utilities 





&. 


CONTROL |-| RESET |: see Section 1.3.2 


system calls: see Appendix F 


POKE statement: see Section 7.1.2 


Apple lle Monitor program: see Apple 
lle Reference Manual 


US executes a machine-language 
function routine 








subroutine at the designated address; when the subroutine is fin- 
ished, execution continues with the statement following the CALL. 
For example, 





CALL G4668 — executes machine-language 
subroutine beginning at ad- 
dress G4668 

Warning 


Make sure the address you give in the CALL statement is the beginning 
of a valid machine-language subroutine! A misdirected CALL can have 
unpredictable and probably unpleasant consequences, such as hang- 
ing the system or dropping you into the Monitor. If any of these calamities 


befall you, use { conTRoL |-[ RESET |to regain control of the system. 


The Apple Ile’s built-in firmware contains many useful subroutines 
accessible with the CALL statement; see Appendix F, “Peeks, 
Pokes, and Calls,” for details. 





You can also use CALL to execute machine-language subroutines 
of your own, which you have stored into memory with the POKE 
statement, typed from the keyboard via the Monitor, or loaded into 
the computer from a disk or tape. 


lf CALL is given a negative target address, it adds 635 36 (2 tothe 
16th power) to obtain an equivalent positive address. For example, 


CALL -936  isequivalentto CALL G4600 
CALL -868  isequivalentto CALL G46658 
CALL -1998 isequivalentto CALL 63338 


If the target address is notin the range -635333 to + 63335, the 
program will halt with the message 


PILLEGAL QUANTITY ERROR 





The USK Function 


Not for Everyone: This feature is intended for expert programmers 
only, and requires a knowledge of machine-language programming. 
Readers with fewer than sixteen fingers are advised to skip this section. 


The USR (for “user-supplied routine’) function executes a machine- 
language function routine stored into the computers memory by you, 
the user. Such a routine typically performs some high-speed compu- 
tation that cannot be done efficiently, or cannot be expressed at all, in 
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POKE statement: see Section 7.1.2 


Apple Ile Monitor program: see Apple 
lle Reference Manual 


Argument and result passed via floating- 
point accumulator 


Locations $04 to $0C mustcontaina 
MP to the routine 


Applesoft. The argument supplied to the USF function is passed un- 
changed to the machine-language routine, and the result yielded by 
the routine is passed back as the value of the USF call. 


The function routine to be executed with US may be stored into the 
computer's memory with the POKE statement, typed from the key- 
board via the Monitor, or loaded into the computer from a disk or tape. 
When USR is called, the value supplied as an argument is placed 
into the floating-point accumulator in the computer's memory (hexa- 
decimal locations $)D to $43); control is then transferred via 

a machine-language JS (Jump to Subroutine) instruction to 
hexadecimal address $0A (decimal 1 ©). Locations $04 to $0C 
(decimal 1 ® to 1 2) must contain a machine-language JP (Jump) 
instruction to the beginning of the machine-language routine. The 
routine should leave its result in the floating-point accumulator and 
return control to Applesoft with an kk TS (Return from Subroutine) in- 
struction. The contents of the floating-point accumulator are then 
passed back to your Applesoft program as the value yielded by USK. 


Here is a trivial example showing the use of the USF function. The 
machine-language routine shown here simply takes the argument 
value it receives and multiplies it by 8: 


J CALL -1isil —leave Applesoft; enter Monitor 

* OA:4C OO O23 —set up machine-language 
jump to hexadecimal address 
$300 


€# QO300:15 AS 3D 69 G3 853 3D GO 
—enter short machine-language 
routine to multiply contents of 
floating-point accumulator by 


8 

# -C —return to Applesoft 

1 PRIN! USR (3? —execute routine with argument 
value 3 

24 —result displayed on screen 


At hexadecimal address #04, there isa JMP (op code 4C) to hex- 
adecimal address #30. (As usual in 6502 machine language, the 
low-order byte of the address, 0, precedes the high-order byte, 
03.) Beginning at address $300 is a machine-language routine to 
multiply the value in the floating-point accumulator by 8. Back in 
Applesoft, when the function call USR (3) is executed, the argu- 
ment value <3 is placed in the floating-point accumulator and control is 
passed to the machine-language routine via the JMP at location 

$ 0A. The machine-language routine gets the value in the floating- 
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7.1.5 


Novices need not apply 


liA I T waits for a signal from a periph- 
eral device 


mask: a pattern of bits for use in bit-level 
logical operations 








point accumulator, multiplies it by 8, puts the result (2 4) back into the 
floating-point accumulator, and returns control to Applesoft with an 

lk TS instruction (op code &@). The value = 4 is then passed back as 
the result of the USR call. 


To obtain a two-byte integer from the value in the floating-point accumu- 
lator, your machine-language routine should do a JSF to address 
$EO1C.Upon return, the integer value will be in locations $A (high- 
order byte) and #A 1 (low-order byte). 


To convert an integer result to its floating-point equivalent, so that the 
function can return that value, place the two-byte integer in registers A 
(high-order byte) and ‘’ (low-order byte). Then do a JSF to address 

$E 2F 2. Upon return, the floating-point value will be in the floating-point 
accumulator. 





The WAIT Statement 


WAIT 459347, 13 
WAIT 459401; £40, 192 
WATT ADDRA+ Milas Mee 


For Experts Only: This feature is intended for expert programmers 
only, and requires an understanding of bit-masking operations. If you 
think a mask is something you wear on Halloween, you can safely afford 
to skip this section. You won't miss a thing. 


The WATT statement suspends program execution until a specified 
bit pattern appears at a specified memory location. It is typically used 
to wait for a particular status signal from a peripheral device. 


The first expression following the keyword WA I T designates the ad- 
dress of the memory location to be tested. The second expression 
represents a one-byte mask specifying which bits of the designated 
location are of interest: a one bit in the mask means that the corre- 
sponding bit of the memory location is to be tested; a zero bit means 
itis to be ignored. The optional third expression is another one-byte 
mask specifying the bit value to be tested for in each position of the 
memory location: a one bit in the mask tests for a zero bit in the corre- 
sponding position of the memory location, and vice-versa (!). If the 
second mask is omitted, all bit positions specified by the first mask 
will be tested for a one bit. For example, 


Utility Statements 


A 


CONTROL |-|RESET| :see Section 1.3.2 





WATT ADDRs+ 255 —wait for a one bit anywhere in 
location ADDR 

WATT ADDR:+ 2533+ 253 —waitforazerobit anywherein 
location ADDR 

WAIT ADDR: 1 —wait for low-order bit of loca- 


tion ADDR to become i 


WAIT ADDR:s+ 128+ 128 —waitforhigh-order bit of loca- 
tion ADDR to become 0 


WAIT ADDR: 3+ 


PJ 


—wait for low-order bit of loca- 
tion ADDR to become i or 
second low-order bit to be- 
come 0} 


When WATT is executed, the contents of the location specified by 
the first expression are exclusive-or’ed with the mask represented by 
the third expression (if any); the result is then anded with the mask 
represented by the second expression. If the result is nonzero (that 
is, if any of the bits of interest are in the specified state), then program 
execution proceeds; if the result is zero (none of the bits of interest 
are in the specified state), then the test is repeated. Thus program 
execution will be suspended until one of the specified bits is set to the 
specified state by an outside agency (presumably a signal from a pe- 
ripheral device). 


Warning 


If the specified bit pattern never appears, program execution will hang 
forever. Make sure that the memory location you're testing is receiving 
information that will eventually test true. The only way to interrupt a 


WAIT is with (contRot |- 


If AAI T is given a negative target address, itadds 63536 (2 tothe 
16th power) to obtain an equivalent positive address. For example, 


WAIT -16189,% i353 isequivalentto WAIT 49347; 15 
If the target address is not in the range -G3335 to +65335, orif 
either of the masks is not in the range © to 2353, the program will halt 
with the message 


VILLEGAL QUANTITY ERROR 


System Utilities 








7.2 


HIMEM: statement: see Section 7.2.1 
LOMEM: statement: see Section 7.2.2 


FRE function: see Section 7.2.3 


7.2.1 


HIMEM: sets upper limit of available 


program memory 


Loading DOS resets HIMEM: 


Apple lle Monitor program: see Apple 
lle Reference Manual 


A word to the wise A 





Memory Management 


The features discussed in this section are used to control the way 
Applesoft allocates memory space for your program: 


@® TheHIMEM: statement sets the upper limit of available pro- 
gram memory. 


e@ The LOMEM: statement sets the lower limit of available program 
memory. 


@® The FRE function determines the amount of remaining memory 
space available to the program. 





The HIMEM: Statement 
HIMEM: 8192 


The HIMEM: statement sets the highest memory address available 
to an Applesoft program for storage of program lines and variables. 
The upper limit of available program memory is set to the value of the 
expression following the keyword HI MEM: . The area above this ad- 
dress is available for use by the Disk Operating System, high-resolu- 
tion graphics, or machine-language programs. 


Notice that the colon is part of the keyword HIMEM: and is required. 


Applesoft automatically sets HI MEM: to the address of the highest 
writable memory (RAM) address available on your computer. On sys- 
tems equipped with disk drives, loading the Disk Operating System 
(DOS) will automatically reset HI MEM: to a lower value in order to 
protect the area of memory occupied by DOS itself. See your DOS 
manual for further information. 


You can change the setting of HIMEM: only by 


@ executing the HIMEM: statement 


typing { CONTROL |-B to the Monitor program 


@ restarting the system 


loading a machine-language program 


Warning 

Resetting HIMEM: above its current value is an extremely dangerous 
practice that can result in writing over the Disk Operating System or 
other vital system information. Wise programmers will carefully investi- 
gate reserved memory areas before writing to them. 


Utility Statements 


PEEK function: see Section 7.1.1 


7.2.2 


_L_OMEM: sets lower limit of available 
program memory — 


DEF FN statement: see Section 2.4.3 


Adding a program line resets 
LWIME DM 4% 


NEW command: see Section 1.2.1 





Acommon use of HI MEM: is to protect your program and high-resolu- 
tion graphics from overwriting each other. See Section 6.2.5, “Protecting 
High-Resolution Graphics,” for details. 


Helpful Hint: The current value of HIMEM: is stored in decimal mem- 
ory locations 1 13 and i 16; to obtain that value, use the expression 


PEER (116) * 2536 + FEER (113) 

If HIMEM: is given anegative address, itadds 63336 (2 to the 16th 
power) to obtain an equivalent positive address. For example, 
HIMEM: -37344 isequivaientio HIMEM: S192 


If the specified address is not in the range -63335 to +6535335, the 
program will halt with the message 


PTILLEGAL QUANTITY ERROR 


lf the specified address is lower than the current setting of LOMEM:, or 
doesn’t allow enough room for the program already in memory, the pro- 
gram will halt with the message 


POUT OF MEMORY ERRUR 





The LOMEM: Statement 
LOMEM: 24576 


The LOMEM: statement sets the lowest memory address available 
to an Applesoft program for storage of variables. The lower limit of 
available program memory is set to the value of the expression fol- 
lowing the keyword LOMEM:. The area below this address is avail- 
able for high-resolution graphics or machine-language programs. 
_.OMEMs: also resets all variables to their initial values and wipes out 
all functions defined with DEF FN. 


Notice that the colon is part of the keyword LOMEM: and is required. 


Applesoft ordinarily begins to store variables at the end of the pro- 
gram in memory. Each time you add, delete, or change a program 
line, Applesoft resets L OMEM: to alocation just above the final line 


of the program. Executing the NE command or typing { CONTROL |-B 
to the Monitor resets LOME™M : to its initial value. 
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A 


Don’t execute LOMEM: from withina 
program 


PEEK function: see Section 7.1.1 


HIMEM: statement: see Section 7.2.1 


7.2.3 


FRE yields amount of available mem- 
ory 





The value of LOMEM: can only be increased from its current setting. 
An attempt to set LOMEM: toa lower value than the one already in 
effect will halt the program with the message 


TOUT OF MEMORY ERROR 





Warning 


Changing LOMEM: during the course of a program is a most danger- 
ous practice that can cause portions of the program or of Applesoft’s in- 
ternal control information to become unavailable, which in turn will 
cause the program to behave in outlandish ways (if at all). Programmers 
who behave with such reckless abandon have only themselves to 
blame. 

a eee ee ee 


Helpful Hint: The current value of LOMEM : is stored in decimal mem- 
ory locations 105 and 16; to obtain that value, use the expression 


PEEK (106) * 256 + PEEK (105) 


If_LOMEM: is given a negative address, it adds 65536 (2 to the 16th 
power) to obtain an equivalent positive address. For example, 


LOMEM: -49152 isequivalentto LOMEM: i6384 


lf the specified address is not in the range -65535 to +65535, the 
program will halt with the message 


TILLEGAL QUANTITY ERROR 

lf the specified address is higher than the current setting of HIMEM: , 
or lower than the address of the highest memory location occupied by 

the current operating system (plus any currently stored program), the 

program will halt with the message 


‘OUT OF MEMORY ERROR 


ee ee ee 
The FRE Function 


The FRE function yields the number of bytes of unused writable 
(RAM) memory available to the running program. For example, 


LET AVAIL = FRE(Q) —set AYATL to amount of 
available memory remaining 


Notice that the name of the function is FRE, not FREE. 


Utility Statements 


HIMEM: statement: see Section 7.2.1 


Argument required but ignored 


Memory Management 





If the number of free bytes exceeds 32767, F RE yields a negative re- 
sult; adding 63336 will give you the actual number of free bytes: 


IF FRE(O) < O THEN AVAIL = FRE(CO) + 


63536 


If you have set HI MEM: beyond the highest RAM address in your 
Apple lle, F RE may yield a value higher than the computer's actual 
memory capacity. The reliability of such a value is to be taken lightly. 


Stranger Than Fiction: The argument given to F RE is ignored, and 
has no effect on the operation of the function. However, you can't leave it 
out—you must include an argument expression of some kind to “keep 
the parentheses apart.” What you use for an argument expression 
doesn’t matter, but if Applesoft can’t evaluate it as a legal expression, 
you'll get an error halt. 


How Applesoft Manages Free Space: The amount of free space re- 
ported by F RE is the number of bytes remaining below the string stor- 
age space and above the numeric array and string pointer array space 
(see Section H.2, “Applesoft Memory Allocation”). When Applesoft 
changes the contents of a string variable during the course of a program 
(say from "CAT" to "DOQG"), the characters in the old string 
("CAT") are not erased from memory; Applesoft simply allocates 
some fresh space to hold the new string ("DQG"). As aresult, charac- 
ters left over from unused strings take up “dead space” and slowly fill 
memory from H I MEM: down toward the top of the array space. 


Applesoft will automatically clear out these leftover characters when the 
bottom of string space “collides” with the top of array space. But if you’re 
using any of the free space for machine-language programs or for high- 
resolution graphics, they may be overwritten. 


Light Housecleaning: The automatic “housecleaning” just described 
takes time (anywhere from a fraction of a second to over two minutes, 
depending on the number of string variables your program is using). Fur- 
thermore, such housecleaning occurs at unpredictable moments— 
whenever your string and array spaces happen to collide. If it happens 
while Applesoft is in the middle of displaying a message on the screen, 
for instance, it can cause unfortunate confusion for your program’s user, 
who will be left waiting for the computer to finish displaying a half-deliv- 
ered message. : 


The F RE function provides a tool for warning the user that the computer 
will be busy for a while. The address of the current beginning of string 
space is kept in locations i 1 1 and 1 i 2 ofthe computer's memory; the 
end of array space is kept in locations 1 09 and 1 1 0. Whenever Apple- 
soft needs to allocate more memory, it compares the contents of these 
locations; if they differ by less than one, Applesoft does its automatic 
housecleaning. 








7.3 


7.3.1 


TRACE displays line numbers as they 
are executed 


[ CONTROL |-C: see Section 1.3.2 





Since Applesoft checks these locations, so can you. When the differ- 
ence between them starts getting close to zero, it’s time to display some 
kind of “don't worry” message and force housecleaning. Using a state- 
ment of the form 


LF APEERAL 2) #256 +. PEER C111) ) 
—(PEER(I 10) 4206 + FPEEK(I0OS)) 2 « [HEN 
PRINT ~FPLEAS- GIANG Byi+3" = 8 = PRE (0) 


periodically within your program will force housecleaning to occur and 
will prevent such confusion. 


Since the housecleaning can take as long as several minutes each time 
itoccurs, don't do it too often. It’s besttouse FRE (0) when youneed 
a pause anyway—such as after you write information onto a disk, or 
while the user is reading information on the display screen. 


Debugging Facilities 


This section details two Applesoft commands used as debugging 
aids: TRACE and NOTRACE. They’re useful when a program isn’t 
behaving as intended and you need to find out why. 





The TRACE Command 
TRACE 


TRACE causes Applesoft to display the line number of each state- 
ment it executes. Each line number displayed is preceded on the 
screen by a number sign (#). For example, the program 


10 TRACE 
©eQ 1 = — + 1: I= 1+4+H1 

—two statements on line 20 
30 J = J + Lt J = J + ] 

—two statements on line 30 
40 GOTO 20 —loop forever 


will display the output 


#20 #20 #30 #30 #40 #20 #20 #20 #30 #40 
#20 #20 #30 #30 #40 #20 #20 #30 #30 #40 
#20 #20 £30 #30 740 #20 #20 #30 #30 #440 
#20 #20 #30 #20 #40 #20 #20 #30 #30 #40 
#20 #20 #320 #20 #40 #20 #20 #30 #230 #40 


ad nauseam, or until you press | conTROL |-C, whichever occurs first. 
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NOTRACE statement: see Section 
Toe 


Apple Ile Monitor program: see Apple 
lle Reference Manual 


Using TRACE from within a program 


display formatting: see Section 5.2.4 


Once tracing has been started, it can be canceled only by 


@® executing the NOTRACE statement 


@ restarting the system 


@ typing | conTRoL |-B to the Monitor program 


As the example above shows, T k ACE can be used from within a pro- 
gram as well as in immediate execution. A more realistic use in debug- 
ging would be to test for some error condition and turn on tracing only if 
the error condition holds: 


IF # >? Y UTHER UT RACE —trace if variable values are 
wrong 


Be sure to remove the TRACE statements from your program after 
you've found and exterminated the bug! 


When the program being traced contains display-formatting statements 
(¥TAB, HTAB, TAB, semicolons, commas), line numbers displayed by 
TRACE may appear in a confused fashion or may be overwritten 
entirely. 





The NOTRACE Command 
NOTRACE 


The NOTRACE command cancels the effects of TRACE. After this 
command is executed, line numbers are no longer displayed on the 
screen as Applesoft executes them. 


Debugging Facilities 








Utility Statements 
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Planning the Program 
8.1.1 Program Specification 


What the Program Needs 


What the Program Will and Won't Do 


Validating the Data 
Displaying the Results 


8.1.2 Program Layout 


The Initial Layout 
Refining the Layout 


Writing the Code 


8.2.1 
8.2.2 
8.2.3 
8.2.4 
8.2.5 
8.2.6 
8.2.7 
8.2.8 
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Preliminaries 

Display the Menu 

What’s the Postage Class? 
What Does It Weigh? 

Compute the Charge 

Display the Results 

Calculating Routines 
Consistency-Checking Routines 
The “Keystall” Routine 


8.2.10 The Formatting Routine 
Final Advice to the New Programmer 
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program planning: see Section 8.1 


coding: see Section 8.2 


8.1 


8.1.1 


Good programs take careful planning 


Specifications define what the program 
does and how 


Programming: Bringing It 
All Together 


Good programs don't just happen. Programs that are efficient, eco- 
nomical, and easy to debug and to modify are the result of careful 
planning. This chapter presents a method to facilitate such planning, 
using as its example a program to calculate postage fees for United 
States mail. A copy of this program is included on the Applesoft Sam- 
pler disk; a complete listing can be found in Appendix N. 


Section 8.1, “Planning the Program,” shows how to develop a list of 
program specifications and how to convert the list into a kind of pro- 
gram outline. 


Section 8.2, “Writing the Code,” shows how to refine the outline 
developed in Section 8.1 into a final Applesoft program. 


Planning the Program 


Although you can afford to be “quick and dirty” for casual or one- 
time-only applications, you'll need to do some preliminary planning 
for more serious ones. In general, the more planning you do the more 
efficient and bug-free your finished program will be. 


To demonstrate some of the principles of program planning, this 
chapter develops a program to calculate postage rates on certain 
classes of mail sent in the United States. 





Program Specification 


Program planning begins with deciding what your program is to do or 
what problem you want it to solve. You might want to design a space- 
war game, a tax planner, or a data-base management system. It 
doesn't matter how simple or how complex the task—whatever It is, 
you have to decide in detail what the program is supposed to do. 


To make writing the program easier, it's a good idea to begin with a 
list of program specifications. This list specifies what information the 


Planning the Program 





What does the program need from the 
user? 


What internal information does the 
program need? 


What won’t the program do? 








program needs, what the program should and should not do, how the 
results are to be presented, and so forth. 


What the Program Needs 


It’s fairly simple to determine what information a postage rates pro- 
gram needs. Since the goal is to determine how much it costs to mail 
an item, and since cost is a function of mail class and weight, the pro- 
gram needs someone or something to tell it what weight item is being 
mailed in what class. To keep things simple, the program will get this 
information from the program user: 


@ The user tells the program the class of mail. 


@ Theuser also tells the program the weight of the item, since pos- 
tage rates are based on both class and weight. 


When the program has the weight and class of mail (for instance, 
three ounces of first class), it needs to determine the postage based 
on some scale. It must either calculate the postage with a formula or 
look up the rate in a table stored in the computer’s memory. Since all 
computers are inherently stupid and must be told everything, you 
have to include formulas or tables with which your computer can 
work: 


@ The program includes formulas and/or tables of postage rates for 
various weights and classes of mail. 


@ The program includes information on the maximum allowable 
weight in each class. 


This last specification is a matter of postal regulations; first class mail 
above 12 ounces is called priority mail and is charged at a different 
rate; 70 pounds is the maximum weight for priority mail; and so forth. 
Program planning, then, calls for information often outside of the pro- 
grammer’s immediate purview. That’s why God created libraries and 
telephones—so that programmers could obtain information they 
dont already have. 


What the Program Will and Won’t Do 


Deciding on the limits of a program is often as important as determin- 
ing what the program is supposed to accomplish. United States mail 
has four classes, several types within certain classes, optional extras 
like insurance and various forms of registry, and so forth. To make de- 
signing and writing the program simpler, we'll assume that our pos- 
tage is never below first class, and further that we never insure or 
register mail (what fools these mortals . . . ). We'll also assume that 
packages sent by overnight delivery (express mail) never weigh more 
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Humans will be human... 


Give your user clear instructions 


What if the information is invalid or 
inconsistent? 


than nine pounds and always travel in the same postal zone: 


@ The program is limited to express, first class, and priority mail 
(One zone only). 


@ The heaviest express mail package will be nine pounds; first 
class and priority mail may be of any weight, up to Post Office 
limits. 


Validating the Data 


Now that the program has information both from the user and from its 
own internal resources (charts of rates and so on), it must check the 
validity and consistency of the information. 


First for validity: does the information the user typed make sense in 
terms of what the program expected? If the program needs a digit for 
the weight of a letter, what should it do if it gets a word? In designing 
any program, it’s important to remember: 


@ Mosthumans do not possess genetic information about what to 
type into computers. 


@ Mosthumans make mistakes. 


The program, then, must display clear instructions telling the user 
what to type (kind of information needed) and what form to use 
(letters, digits, words): 


@ The program will display a list of classes of mail on the screen, 
with instructions for the user about what to type. 


e After it gets the class of mail, the program will solicit the weight 
from the user with proper instructions. 


@ There willbe amechanism for accepting valid information and 
rejecting invalid information (that is, there are error-handling 
provisions). 


Naturally, if the program rejects invalid information, it must try again 
to get valid information from the user: 


@ finformation is rejected as invalid, the program will continue to 
solicit information until it gets what it needs. 


Now to consistency: although a user might plausibly ask the cost of 
sending a five-pound package via first class mail, only the program 
knows (by checking its table of limits) that five pounds is too heavy for 
first class. It must notify the user that some other action is called for: 
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How are the results presented? 


What happens when the program is 
finished? 


Table 8-1 Final Specifications for the 
Postage Rates Program 





@ finformation is rejected as inconsistent, the program will notify 
the user with appropriate recommendations for further action. 


Displaying the Results 


The specifications must also include the form in which the results are 
to be given to the user. In this case we'll keep it simple: 


@ The final calculated postage charge will be displayed on the 
screen with appropriate labeling. 


Finally, the specifications must tell what the program does when its 
job is completed. Here, it will repeat the whole process until the user 
types in some kind of “I’m done” signal: 


@ The program will continue to solicit information to calculate new 
postage charges until the user types an “end” signal. 


Reordering the list of specifications into a more logical form, we ob- 
tain the final list shown in Table 8-1. 


@ The program will display a list of classes of mail on the screen, with instructions for 
the user about what to type. 


@ The program is limited to express, first class, and priority mail (one zone only). 
e@ The user tells the program the class of mail. 


e After it gets the class of mail, the program will solicit the weight from the user with 
proper instructions. 


@ The user tells the program the weight of the item. 
@ The program includes information on the maximum allowable weight. 


@ The heaviest express mail package will be nine pounds; first class and priority mail 
may be of any weight, up to Post Office limits. 


@ There will be amechanism for accepting valid information and rejecting invalid 
information. 


@ |finformation is rejected as invalid, the program will continue to solicit information 
until it gets what it needs. 


e If information is rejected as inconsistent, the program will notify the user with 
appropriate recommendations for further action. 


@ The program includes formulas and/or tables of postage rates for various weights 
and classes of mail. 


@ The final calculated postage charge will be displayed on the screen with appropriate 
labeling. 


@ The program will continue to solicit information to calculate new postage charges 
until the user types an “end” signal. 
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interactive program: a program that 
conducts a dialog with the user 


8.1.2 


Lay out your program before you start 
coding 


stepwise refinement: a technique of 
program development in which broad 
sections of the program are laid out first, 
then elaborated step by step 


Table 8-2 Initial Layout of the Postage 
Rates Program 


Repeat 
Display menu 
Accept class 
Accept weight 
Compute charge 
Display results 


until done 


Reviewing the list, you can see that the program’s actions fall into a 
natural chronological order: 


1. 


Computer displays prompting messages. 

User responds. 

Program checks validity of responses. 

lf any information is invalid, program solicits new information. 


Program checks consistency of responses. 


oo - | Pp 


lf any information is inconsistent, program solicits clarified 
information. 


Program processes validated information. 
Program displays results and goes back to stage 1. 
You'll find that most interactive programs—programs that carry ona 


“dialog” with a human sitting at the computer—involve most of the 
categories above in roughly the same order. 





Program Layout 


Before rushing to put fingers to keyboard, it’s best to take your plan- 
ning at least one step further. Now is the time for program layout. 
Here you plan out the form for each section of the program as de- 
scribed in both the specification list and the chronological order list. 


The program layout technique presented here is called stepwise re- 
finement. What this means is laying out broad sections of the pro- 
gram, then going back and refining each section step by step. 


The Initial Layout 


Table 8-2 shows an initial layout of the Postage Rates program in the 
broadest terms. The layout says that there are five general sections 
to the program (Display menu, Accept class, Accept weight, Com- 
pute charge, and Display results), and that the program is to repeat 
this sequence of steps in order until somehow told to stop. 


Each section can now be treated as an independent module, to be 
designed and coded separately. The smaller the chunks of program 
you work with and the more independent each chunk is, the less 
chance for error and the easier the program will be to debug. 
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Refine each module 


Table 8-3 First Refinement of the Pos- 
tage Rates Program 








Refining the Layout 


Now that we have the program laid out in skeleton form, we can begin 
to put some flesh on the bones. Table 8-3 shows the first refinement, 
in which each of the broad steps in the initial layout is spelled out in 
more detail. 


Repeat 


Display menu: 
List choices 


Accept class: 
Instruct user how to choose 
Repeat 
Get postage class from user 
until valid menu item 


Accept weight: 
Repeat 
Instruct user how to type 
Get weight from user 
until consistent 


Compute charge: 
Calculate from formula or look up in table 


Display result: 
Format result with dollar sign, trailing zeros 
Label and display result 
Wait for signal from user before proceeding 


until user signals end 


At this point, many programmers would take outline in hand and at- 
tack the keyboard. (With an outline?) But a couple of the modules 
need further refinement: both the Accept weight and the Compute 
charge modules need to do specialized processing depending on 
the class of mail specified by the user. The new information in the 
Compute charge module comes from examining postage rate charts. 
First class mail is fairly regular, so a formula can be used to compute 
the charge. Express mail follows no regular pattern, so it’s easier to 
create a table of charges. Priority mail requires a combination of both 
formula and table. The final program layout is shown in Table 8-4. 
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Table 8-4 Final Layout of the Postage 
Rates Program 


Repeat 


Display menu: 
List choices 


Accept class: 
Instruct user how to choose 
Repeat 
Get postage class from user 
until valid menu item 


Accept weight: 
Repeat 
Instruct user how to type 
Get weight from user: 
Check validity of response 
Express? 
If item more than 9 pounds 
then suggest alternative 
First class? 
If item more than 12 ounces 
then suggest alternative 
Priority? 
If item less than 12 ounces 
then suggest alternative 
If item more than 70 pounds 
then suggest alternative 
until valid and consistent 


Compute charge: 
Express? 
Look up charge in table 
First class? 
Calculate charge from formula 
Priority? 
If item less than 10 pounds 
then look up charge in table 
otherwise calculate charge from formula 


Display result: 
Format result with dollar sign, trailing zeros 
Label and display result 
Wait for signal from user before proceeding 


until user signals end 
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8.2 


Use the layout as a guide while writing 
code 


Methodical program development 
makes programs easy to debug and 
modify 


The author makes no warranties, either 
express or implied... 


8.2.1 





Writing the Code 


Now that you've refined the program layout to a sufficient level of 
detail, you're finally ready to start writing code. The layout is only a 
guide; it isn’t the last word. As you write and test the actual program, 
you may find you need to make changes in your original design. 
That’s perfectly all right; use the layout to keep you on track. 


What follows in this section represents one way to turn the outline 
into a working program. It isn't the only way—a hundred program- 
mers would produce a hundred different programs for the same task. 
It does, however, work; and because it’s been developed in an or- 
derly, methodical way, it’s also logically organized and easy for a hu- 
man reader to follow. This is an important consideration, because it 
makes the program easy to debug and easy to modify. (Almost all se- 
rious programs need to be modified at some time or other, often by 
someone other than the original programmer.) 


Hysterical Note: Any resemblance between the following program and 
true top-down structured code is purely coincidental and probably hallu- 
cinatory. The perceiver of such a resemblance is advised to seek psy- 
chiatric aid promptly. 





Preliminaries 


Your program should begin with a block of REM statements identify- 
ing the program and describing what it does. Most programmers add 
their own name and the date of the program’s current version: 


10 REM POSTAGE RATES 
—name of program 
Zu 4 —colon leaves line empty 
3O REM DETERMINES POSTAGE FEES 
—what program does 
40 REM FOR EXPRESS:+; iST CLASS: 
OO REM AND PRIORITY MATL 
—empty line inserted by embea- 
ding | CONTROL |-J (line feed) 
at end of REM statement in 
line 30 
GO REM We 2/01/82 
——number and date of this 
version 
70 REM BY JOHN SCRIBBLEMONGER 


——programmer's credit line 
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Display the Menu 


Now you can refer to your outline and base your code directly on it. 
Notice the REM statements introducing the different sections. All the 
comments marked here by dashes (—) could also be included as 
REM statements: 


100 REM MENU OF POSTAGE CLASSES 
—LEONTROL J-J here 


110 HOME —begin with a clear screen 
120 TITLES = "POSTAGE RATES" 
130 PRINT 


140 HTAB 21 - LEN (TITLE#) / 2 
—formula to center title 

150 PRINT TITLES 

iGO YVTAB 6 

170 PRINT "i. ArPREBO 

180 PRINT “2s FIRST CLASS” 

i190 PRINT "3. PRIORITY" 

200 PRINT 

“10 PRINT "dad. END THE PROGRAM" 
—the escape hatch 





What’s The Postage Class? 


This section finds out what mail class the user wants to use. Note 
the use of -.J, the line feed character, to set off the REM 
statements for easier reading (line 300): 


300 REM —| CONTROL |J-J here 
GET CLASS OF MAIL 


—|CONTROL |-.J here 


310 YVTAB 14 
320 PRINT "Press the number of your 


choice:" 3 —semicolon keeps response on 
same line 
330 GET C —only one keypress needed; 


cuts down on error possibili- 
ties. Note use of string variable 
to get number; avoids type 
mismatch errors 
335 REM —| CONTROL J-J here 
CHECK FOR VALIDITY 
—another { CONTROL }-.J (last 


time this is noted) 
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340 [IF C$ = "4" THEN END 
—end program if user types a 4 


330 IF VAL (C$) = O AND VAL (C$) «¢ 4 
THEN 380 —skip next two lines if valid 
choice typed 


360 PRINT CHRE(7)3 CHRS(7) 5 
—beep twice to get attention 


370 GOTO 330 —response was invalid; try 
again 
380 PRINT C$ —since choice accepted via 


GET, itisn’t displayed on the 
screen. Display it back to user 

390 C = VAL (C$) —need this value later to deter- 
mine what section of program 
to branch to for proper 
processing 





What Does It Weigh? 


Now the program asks the user for the weight of the letter or package. 
The program makes sure that the user follows the instructions and 
types anumber for the weight and a symbol (0 or P) for ounces or 
pounds. Notice that the program accepts both the numeric weight of 
the item and the ounce/pound designation in the same string (line 
O30), 


2O0O REM 
GET WEIGHT OF ITEM 


203 YVTAB 16 


210 PRINT "Please enter the WEIGHT - a 
number Plus an O (for ounces) or aP 
(for Pounds) - and press the RETURN 
Key: "4 —prompting message to tell 
user what information to type 
and how to type it 


220 CALL -868 —clear to end of line; useful to 
erase any errors that might be 
typed 

230 INPUT ""s WS —semicolon suppresses ques- 
tion mark 


S40 WIS = RIGHTS (WH; 1) 

—rightmost letter should be 
either 0 or FP; use it later to see 
if weight is consistent with 
postal regulations 
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oeO Wo = VAL (WS) —how many ounces or pounds? 
too hee 
WAS ENTERED WETGHT VALID? 
260 IF Wo? 0 AND (WisS="0" OR WisS="P") 
THEN 710 —if a weight was typed, and if 


last character was either 0 for 
ounces or F for pounds, then 
proceed 
O70 PRINT CHR (€7)5 CHR (7) 
—beep twice to get attention 
280 GOTO 300 —entry was invalid; try again 


lf the program has progressed this far, then everything typed by the 
user is valid from the computer's point of view. However, the user's 
choices still may not be consistent with postal regulations or the pro- 
gram’s limitations. First class letters must weigh less than 12 ounces, 
the program can’t handle express mail above a certain weight, and 
so on. This section of code uses the value of variable C (setin line 
35) to direct control to the proper subroutine to check for 
consistency. 


700 REM 
CHECK CONSISTENLY 


710 ON C GOSUB 10000; 11000, 12000 
—branch to appropriate subrou- 
tine to see if weight typed is 
within postal rules or program 
limitations for mail class 
chosen 
729 IF NOT EFLAG THEN 310 
—if no inconsistency detected in 
subroutine then proceed with 
processing 
730 GOSUB GOOO0O0 : REM KEYSTALL 
—wait for user to acknowledge 
message 
740 EFLAG = 0 —clear error flag set in 
subroutine 
7O0 CLEAR —reset all variables, clear 
arrays, etc. 
760 GOTO 100 —restart program loop 
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Compute the Charge 


Now that everything checks out all right, the program can proceed to 
calculate the postage. The calculation is different for each of the 
three classes of postage, so there are three separate calculating rou- 
tines. Again, what routine the program goes to depends on the value 
of C, the number representing the postal class chosen by the user. 


900 REM 
FIND APPROPRIATE CODE FOR 
PROCESSING —everything is valid and consis- 
tent; now program can solve 
for the postage rate! 


910 ON C GOSUB 10004 2000+ 3000 
—branch to proper calculating 





routine 
920 GOSUB GidoOd : REM FORMATTER 
—format result for display 
930 PRINT 
Display the Results 


It’s finally time to display the result! 
939 REM 
DISPLAY RESULTS 


940 PRINT "POSTAGE NEEDED: $"3 T4 
—finally, the postage due! 





930 GOSUB GOO00 : REM KEYSTALL 
—dont go on until user is ready 
960 CLEAR —prepare for restart... 
970 GOTO 100 —...and do it. 
Calculating Routines 


The following three subroutines do the actual rate calculations, 
based on formulas, tables, or both. The rates for express mail are 
fairly straightforward; they are based on a table created in the ex- 
press mail consistency-checking routine at line 10000. First class 
rates couldn't be simpler; a little arithmetic is all that’s needed. Prior- 
ity mail is another story, however; when you get to it, you'll find an 


explanation. 


Joa. hel 
SUBROUTINES BEGIN HERE 
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1000 REM 


APRESS MAIL CALCULATION 


INT (Wo + .99) 

—weight must be increased to 
compensate for fractions; 
postal rates read “NOT MORE 
THAN x POUNDS” 

1020 T = R (hW) —rate array filled in express mail 
consistency-checking routine 
(line 10000) 
1030 RETURN —end routine 
£000 REM 
FIRST CLASS CALCULATION 


£010 T = .20 + INT (W + .99 - 1) * 1? 
—first class rate is 20 cents first 
ounce plus 17 cents for each 
additional ounce or portion 
thereof (April, 1982 rates) 
2020 RETURN —end routine 


=. 
| 


LOL 


Although there is something approaching a pattern to priority mail 
charges, the pattern is obscure at best. This is especially true for the 
first ten pounds. Pounds 1 through 5 are charged by the half-pound; 
pounds 6 through 10 are full-pound charges. It's simpler and quicker 
to use a table for these charges (lines 3030 to 3140) than to figure 
out a formula. 


Weights over 5 pounds follow a more regular pattern than the first 5; 
they are all charged in full-pound increments. Furthermore, each five 
pounds costs $2.38. Unfortunately, the cost for pound 6 is different 
from the cost for pound 7, and so on. What it boils down to is that 
5-pound lots can be charged at the same rate (line 31 70), and 
anything that isn’t a multiple of 5 must be looked up in a table (lines 
Slovo 3220). 


If all this strains credulity, refer to United States Mail Service poster 
103, November 1981. 


SU KEM 
PRIORITY MAIL CALCULATION 


3010 W = INT (W + ,.99) 
—compensate for partial ounces 
or pounds 
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3020 


L3 
ra 
a 


3030 
3040 


SoU 
3060 
3070 
3072 
3078 
3080 
3U50 
3100 
S1iid 
3120 
3130 
3140 


wih 
3160 


was 


3180 


shal 


S20 
3210 





IF i 10 THEN 3160 
—go to line 3160 for weights 
greater than 10 pounds 
(ounce weights converted to 
pounds in consistency subrou- 
tine starting at line 1 2000) 
REM 
PRIORITY RATES TO 10 POUNDS 
IF Wei= 1 THEN T = 2,24 
IF Woe 1 AND Wet= 1.53 THEN 
T = 2490 —rates in half-pound increments 
IF Woe 1.5 AND Wei= 2 THEN 
T = 2.094 
IF WW =< AND Wo i= 2.3 THEN 
T = 2.78 
IF Woe 2.3 AND Wt= 3 THEN 
TT = 8.01 
IF WW 3 AND W <== 3.5 THEN 
T = 3-25 
IF WW 3.5 AND W <= 4 THEN 
T = 3.49 
IF id 4 AND Woti= 4.5 THEN 
T = 3-73 
TF ld 4,3 AND Wo «i= 3 THEN 
T = 3.97 
IF Woe 3 AND Wei= G6 THEN T = 4.44 
—rates by the pound now! 
IF WW G AND Wei= 7 THEN T = 4,92 
IF WW 7 AND W t= 8 THEN T = 3,39 
IF ll 8 AND Wi= 9 THEN T = 3.87 
IF Woe 9 THEN T = 6.35 
GOTO 3240 —branch to RE TURN statement 
REM 
PRIORITY RATES FOR OVER IO POUNDS 
Ti = INT (W / 3 - 1) * 2.38 + 3.97 
—first 5 pounds cost $3.97; each 
added 5 pounds cost $2.38 
Wi = W - INT (W / 3) * 5 
—how many odd pounds are 
there (pounds that are not 
multiples of 5 and must be 
charged at a special rate)? 
IF Wi = 1 THEN T2 = ,.47 
IF Wi = 2 THEN T2 = ,.95 
IF Wi = 3 THEN T2 = 1.42 
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3220 IF Wi = 4 THEN Te = 1,90 


32390 T = Til + Té —add the 5-pound-multiples rate 
to the odd-pounds rate 
3240 RETURN —end routine 





Consistency-Checking Routines 


The next three routines make sure that first class letters aren't too 
heavy, that the requested rate can be calculated by the program, and 
in general that the program can deliver what the user wants. The ex- 
press mail routine begins by loading its rates into a table (it gets the 
rates from a DATA list; DATA lists are excellent places to store infor- 
mation you might need in a program); then it checks to see if ithas a 
rate for the package being sent. First class just makes sure that the 
package weighs 12 ounces or less; that’s the maximum weight for a 
first-class item. Priority mail also has an easy job; it just makes sure 
the package weighs more than 12 ounces but not more than 70 
pounds. 


10000 REM 
EAPRESS MAIL CONSISTENCY CHECK 


10010 DATA 3.35+ 39,9537 9.585+ 9,590, 
190,30, 10,65% 11,00, 11.40, 


li./3+ 0 —express mail rates; © at end is 
“last item” flag 
LO02Z0 K = O —set up counter to check how 
many rates are read from 
DATA list 
1O030 K = K + i —increment counter 
10040 READ R CA —put price into proper array 
element 
10030 IF R (x) = 0 THEN 10070 
—price of © marks end of list 
10060 GOTO 10030 —get next price 
10070 K = K - | — includes count of “last item” 


flag from 109030; subtract it 
from count since it’s a 
“dummy” item 


10080 IF Wis = "“P" THEN 10100 
—next line is for ounces only 
10090 W = W / 16 —convert ounces to pounds 


10100 IF We=xX THEN 10140 
—if weight in pounds is covered 
by the rate chart, then go 
ahead 
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LO110 
10120 


LO130 


1O140 


11000 


L1io10 


11020 


11030 


11040 


11030 


11060 


12000 


12010 


12020 


12030 
12040 


12050 


12060 


12070 
1Lf080 
L20sg0 





PRINT 
PRINT CHR 


(7)d5 "TOO 
PLEASE CALL 


(7)3 CHRS 
HEAWY FOR MY TABLES - 
THE POST OFFICE” 

—sorry; can't help you 


EFLAG = I —set flag indicating inconsistent 
weight/type; will be checked at 
line 720 
RETURN —end routine 
REM 
FIRST CLASS CONSISTENCY CHECK 
IF Wié? = "O" AND Wd i2aGl 
THEN 11060 —OK if not more than 12 ounces 
PRINT 
PRINT CHR (€7)5 CHR#(7)5 "TOO 
HEAVY FOR FIRST CLASS" 
—sorry—inconsistent! 
PRINT "TRY PRIORITY MAIL" 
—suggest alternative 
EFLAG = 1 —set flag indicating inconsistent 
weight/type; will be checked at 
line 720 
RETURN —end routine 
REM 
PRIORITY MAIL CONSISTENCY CHECK 
IF WiéS = "P" THEN 12090 
—if in pounds, then skip down 
IF kW lf THEN 12080 
—skip down if weight is between 
12 and 16 ounces 
risa 
PRINT CHRS (7)5 CHRS (7)35 
“TOO LIGHT FOR PRIORITY MAIL -" 
—too light! 
PRINT "TRY FIRST CLASS" 
—suggest alternative 
EFLAG = ji —set flag indicating inconsistent 


weight/type; will be checked at 
line 720 
—branch to end of routine 
—convert ounces to pounds 
THEN 12150 
—tfinal check: is item on the 
charts? 


GOTO 12150 
Wo= W / 16 
IF Woet= 70 
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12100 PRINT 
iZiiO PRINT CHRS (7)s CHRS (7); 
"TOO HEAVY FOR PRIORITY MAIL -" 


—off the charts 
12120 PRINT "TRY ONE OF THE AIR EXPRESS 
COMPANTES" —too big for the Post Office! 
l2130 EFLAG = i —set flag indicating inconsistent 
weight/type; will be checked at 
line 720 
12150 RETURN —end routine 





The “Keystall” Routine 


The “keystall” routine interrupts execution of the program and waits 
for the user to press a key before going on. The GET statement in 
line GO040 actually does the waiting; when the user presses a key, 
the program continues. What key the user presses doesn't matter— 
the program doesn’t care what value is assigned to A$. 


veges KEM 
UTILITY ROUTINES 
—routines useful for various 
tasks but ancillary to rest of 


program 

GO0000 REM 

KEYSTALL —routine to interrupt program 

until user presses a key 

GOOLO YVTAB 24 —move cursor to screen bottom 

GOOLZO INVERSE —set text to appear black-on- 
white 

GOO3O PRINT "PRESS RETURN TO GO ON..."3 

GO0d0O GET AS —wait for keypress 

GO030 NORMAL —restore ordinary white-on- 
black 

GOOG0O RETURN —end routine 





The Formatting Routine 


After the postage charge is calculated, the program branches to this 
final subroutine. Here the final result is checked to see how it will look 
when it is displayed. Does it have a decimal point? Applesoft sup- 
presses trailing zeros after a decimal point, but people are used to 
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seeing them when dealing with dollars and cents. The formatting 
subroutine adds trailing zeros as needed. 


61000 REM 
MONEY FORMATTER 
—adds zeros after the decimal 
point where needed 


61010 TS = STR (¢7T)} —turnthecalculated postage 
fee into a string 
GiOfO IF T = INT (TT) THEN TS = TH + 


hy OO" —if charge is in whole dollars, 
add a decimal point and two 
zeros 
G1030 IF ASC (RIGHTS (T#$+2)) = 46 THEN 
Se = 1% + "0" 


—if second character from the 
right is a decimal point (ASCII 
code 46) then number has 


only one digit to right of deci- 
mal—so adda "0" tothe 
string 

Gid0do RETURN —end the routine 





Final Advice to the New Programmer 


The program planning methods discussed and demonstrated in this 
chapter won't necessarily work for everyone. Different people have 
different programming styles, and some people won't be comfortable 
with the (perhaps) coldly logical model presented here. What's im- 
portant is to find a style that works for you. Programming is a logical 
art; it shouldn't be a confining one. Be as creative as your own inter- 
nals will let you, remembering that poets also plan. 


Keep in mind as you learn to program, please, when a bug is as hard 
to find as cheap gas, that deep down at the bit level—down where the 
computer deals with the only things it really understands—there are 
only zeros and ones. 
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index 


A 


ABS function 38,215 

absolute value 38,215 

addition 32, 36, 86 

American National Standards 
Institute (ANSI) 3 

American Standard Code for 
Information Interchange, see 
ASCII 

ampersand character (&) 246 

AND 35,175 

animation 150 

annunciators 131, 262, 263 

ANSI: see American National 
Standards Institute 

Apple Ile 80-Column Text Card, see 
80-Column Text Card 

arctangent 41,216 

argument of functions 37, 38, 125, 
173, 179 

argument variable 44 

arithmetic functions 38 

arithmetic operators 31 

array(S) 26, 29, 77ff, 217, 228, 248, 
249, 268, 275ff, 293ff, 298 
dimensions 79, 80 
elements 29, 77, 269 
names 29,77 
storage 1/79 
variables 275ff 

arrow keys 18, 20 

ASC function 215 

ASCII (American Standard Code for 
Information Interchange) 19, 82, 
215, 241ff, 258 

assignment statement 30, 215, 
224, 251, 296 

asterisk (*) 32 

ATN function 41,216 

auto-repeat 19,20 


index 





B 


backslash character(\) 4,18 
BAD SUBSCRIPTerror 79,248 
bell character ({CONTROL|-G) 130 
BLOAD command 158 
body of loop 55 
booting 96,112 
branch 49ff, 220 

conditional 51 

unconditional 50,220 
built-in arithmetic functions 38ff 


Cc 


CALL statement 71, 136, 216, 249, 
253ff, 281, 294 

CAN’T CONTINUE error 248 

[CAPS LOCK) key 4 

caret(*) 31 

cassette input 110 

cassette output 131, 264 

Celsius 44 

charactercodes 82 

CHR function 91,216 

CLEAR Command 9, 30, 129, 216, 
294 

colon(:) 5, 98ff, 105, 106, 177, 192, 
246, 267, 296, 301 

color, see display color 

COLOR= statement 137,216 

comma(+) 98ff, 105, 113, 114, 115 

commands, see names of 
commands 

concatenation 83, 84, 100, 251, 
295 

conditional branch 51 

constants 268 

CONT command. 16, 17, 73, 216, 
247, 248 

control characters 100, 101, 241 














(EONTROL] key 15, 16, 18, 241 





-@ 98, 107 
-B 176,177, 181 
-C 15ff, 50, 58, 69, 72, 
98, 107, 159, 180, 216 
-G 130 
-H 100, 107 
-.J (line feed character) 
192, 193, 216, 301 
-™ 100, 107 
-(RESET| 13-17, 96, 112, 
161, 162, 166, 171 
-S§ 15 
-*% 18,100, 107 
control 
stack 10, 62ff, 71,227, 265 
statements 49ff 
COS function 40,217 
cosine 40,217 
crossed loops 60 
currentinput device 104, 223 
current output device 10, 113, 224, 
228 
cursor 4, 18ff, 97, 113, 115, 119ff, 
220ff, 232, 234, 253, 254 
cursor control 287-288 


D 


DATAstatement 103, 105, 108, 
217, 228, 229, 250 

debugging 11,180 

DEF FNstatement 44, 177, 217, 
249 

deferred execution 4, 5,9, 247 

degrees 44 

DEL command 6, 7,217 

|DELETE | key 7 

DIMstatement 79, 217, 251, 293, 
295, 298 

disk 12ff, 112, 156,230 

Disk Operating System (DOS) 12, 
14, 16, 105, 157, 176, 265, 298 

display color 137ff, 160, 216, 220ff, 
251 

display screen 111 

division 32 

DIVISION BY ZEROQerror 248 

dollar sign (#) 26, 29, 82, 88, 251, 
259 

DOS (see Disk Operating System) 

double quotation marks (") 28, 81, 
99, 102, 270 

[DOWN-ARROW | key 18, 19, 241 

DRAW statement 151, 155, 156, 
160, 161, 162, 163, 164, 218, 230, 
231 














index 





E 


e 42 
editing 287-288 
Eighty-Column Text Card 4, 112, 
114, 115, 119, 124, 125, 127, 222, 
254, 287ff 
END statement 17, 73, 216, 218, 
251, 269, 294 
equal sign (=) 30, 34, 44, 129, 137, 
145, 163, 246 
equal to(=) 34 
error 
codes 68, 69, 247ff 
messages 247ff 
errorhandling routines 67ff, 229, 
247, 264 
restoring normal 71 
escape mode 19, 287 
key 20, 242 
-@ 20,255 
-A 20 
-B 20 
-C 20 
-D 20 
-E 20 
-~F 20,255 
-I 19,20 
-J 19,20 
-~K 19,20 
-M 19,20 
exclusive-or 175 
execution of program 16 
xP function 42,218 
expansion slot 96, 111 
exponential 42,218 
exponentiation 32 
expressions 31ff 
EXTRA IGNORED message 99, 
105 


F 


Fahrenheit 44 

false 33ff 

FILE NOT FOUNDerror 14 

FLASH statement 127, 128, 218, 
226 

floating-point accumulator 173 

FN keyword 45, 219 

FOR statement 55ff, 219, 225, 271 

FORMULA TOO COMPLEX error 
248 

FP command 291 

fractions 33 

FRE function 178,220 

freespace 275 


full-screen graphics 136, 138, 148, 
144, 146, 221, 260 
functionnames 44 
functions 37ff, 173, 177, 229 
argumentof 37, 38, 125, 173, 179 
built-in arithmetic 38 
call 37, 38,45 
names 44 
user-defined 44-45, 217 
ABS 38,215 
ASC 215 
ATN 41,216 
CHR 216 
COS 40,217 
EXP 42,218 
FRE 178,219 
INT 39,223 
LEFT# 100, 223, 249 
LEN 224 
LET 215 
LOG 42,224,249 
MID 100, 225, 249 
PEEK 130, 131, 177, 178, 180, 
247, 249, 253ff 
PDL 109, 227 
POS 125,228 
RIGHT# 100, 229, 249 
RND 43,229 
SCRN 141,231 
SGN 39, 231 
SIN 40,231 
SPC 113, 120-121, 231, 249 
SOR 40,232, 249 
STR 232 
TAB 113,120, 121, 123, 126, 
181, 232, 233, 249, 254 
TAN 4,233 
USR 172,233 
VAL 102, 105, 233 


G 


GAME |/O connector 109 

GET statement 16, 19, 104, 220, 
249 

GOSUB statement 61ff, 220, 227, 
229, 251, 293 

GOTO statement 50, 53, 64, 71, 
220, 251, 265, 293 

GR statement 136, 140, 220, 258, 
259, 261 

graphics 119, 135ff, 258 

greater than(>) 34 

greater than or equal to (+ = or = =) 
34 

groundloop 297 


index 





H 


hand control 109, 262 

hand control connector 109, 131, 
262, 263 

HCOLOR= statement 145, 160, 220 

HGR statement 143, 145, 149, 161, 
162, 220, 258, 259 

HGR2 statement 144, 145, 149, 
161, 162, 221, 259 

high-resolution graphics 136, 140ff, 
150, 176ff, 218, 220ff, 230, 261 

HIMEM: statement 149, 156, 165, 
176, 179, 221, 250, 275, 299 

HLINstatement 139, 221 

HOME statement 221, 254 

HPLOT statement 146, 161, 218, 
222, 262 

HTAB statement 120, 122, 126, 
181, 222, 254, 256 

Humpty Dumpty 19 


/ 


IF.++THEN statement 33, 36, 52, 
222, 248, 251, 267, 294 
ILLEGAL DIRECTerror 249 
ILLEGAL QUANTITY error 40, 
42, 52, 66, 86ff, 92, 97, 109, 112, 
121ff 129, 138ff, 146, 147, 161 ff, 
170, 171, 175ff, 249 
immediate execution 4, 7,9, 257 
IN# statement 96, 223 
index variable 55ff, 219, 225, 271 
infinite loop 58 
input 95, 223 
numeric 100 
Input Anything Routine 102 
INPUT statement 16, 17, 97, 
102, 223, 249, 294 
input/output 93ff 
string 99 
INT function 39, 223, 291 
integer 
constants 270 
part 39, 223 
variables 26, 27, 44, 58, 270, 
27 5ff 
Integer BASIC 260, 291 
INVERSE statement 126, 128, 
223, 226 


J 


jIMP (Jump) instruction 173, 233 
Sf (Jump to Subroutine) 
instruction 173, 174, 246 








K 


keyboard 96, 258 
keyword tokens 280ff 
keywords 4 


L 


LEFT# function 86, 100, 223, 249 
LEFT-ARROW] key 18, 19, 100, 
241 
LEN function 83, 85,224 
LET statement 215, 224 
less than (=) 34 
less than or equalto(*=or=<) 34 
line feed character ({[CONTROL |- J) 
192, 193, 216, 255 
line numbers 5ff, 50,51, 64, 65, 70, 
180, 220, 226, 232, 233, 251, 265, 
267, 293, 294 
LIST Command 7, 10, 224 
LOAD Command 14, 110, 224, 298 
LOG function 42,224 249 
logarithm, natural 42, 224 
logical operators 35,54 
logical values 33, 36, 54 
LOMEM: statement 177, 225, 250 
loops 10, 55ff, 219, 225, 250, 270, 
296 
body 55 
crossed 60 
nested 59 
low-resolution graphics 135, 216, 
220, 221, 231, 234, 258, 261 


M 


machine language 172, 176, 177, 
179, 216, 221, 233, 246 

mask 174 

MAT functions 296 

memory allocation 25,275 

memory management 176 

MID#¢function 87, 100, 225, 249 

minus sign(—) 36,105 

mixed graphics andtext 119, 136, 
138, 140, 141, 143, 146, 220, 260 

Monitor program 16, 72, 155ff, 172, 
173, 176, 177, 181 

multidimensional array 80 

multiple input 98 

multiple statements per line 5 

multiplication 32 


N 


naturallogarithm 42, 224 
nestedloops 59 
nested subroutines 62 
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NE command 9, 30, 150, 177, 225 

NEXT statement 55ff, 225,271, 
294 

NEXT WITHOUT FORerror 10, 
60, 249 

NORMAL statement 126, 128, 226 

NOT 935,54 

not equalto(* or?) 34 

NOTRACE command 181, 226 

null character ([CONTROL]--@) 98, 
100, 101, 105 

null string 9, 12, 28, 30, 81, 82, 88, 
97, 98, 100, 106, 251, 294 

number formats 117 

number sign (x) 96, 111, 180, 246 

numeric constants 117,283 

numeric input 100 


O 

ON..+GOSUB statement 65, 226, 
249 

ON..+GOTO statement 51, 226, 
249 


On-screen edit 17 
ONERR GOTOstatement 68, 72, 
226, 229, 247, 239, 264, 265 
\OPEN-APPLE] key 110, 262 
operators 31ff 
arithmetic 30 
logical 35,54 
precedence of 36 
relational 33,54 
OR 34,54 
OUT OF DATAerror 106, 250 
OUT OF MEMORY error 60, 64, 
177, 178, 250, 299 
output 111 
OVERFLOW error 90,91, 250 
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parentheses 37, 250, 276 

PDL function 109, 227 

PEEK function 68, 70, 110, 130, 
131,170, 177, 178, 180, 227, 247, 
249, 253ff, 294 

percent character (%) 26, 28 

period(.) 105 

PLOT statement 138,227 

plotting vector 150ff 

plus sign(+) 36,84, 105, 295 

point of call 61,64 

pointer 275 

POKE statement 71, 72, 129ff, 136, 
143, 149, 155, 156, 159, 170ff, 
227, 249, 253ff, 294 








POP statement 66, 227 
POS function 125, 228 
pound sign (#) 96 
Pk# statement 10, 111,228 
precedence 36 
PRINT statement 105, 113ff, 120, 
121, 223, 226, 228, 231, 232, 254, 
267 
TAB usedin 121ff 
printer 10, 111 
program 275 
execution 16 
layout 189 
lines 3 
planning 185 
specification 185 
prompt character(1) 4, 16, 119, 
247 
prompting message 97, 294 
pure cursormoves 19 
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question mark (7) 97, 116, 294 


R 


radians 40, 41, 44 

RAM (random-access memory) 
176,179 

randomnumbers 43, 229 

READ statement 105, 108, 207, 
217, 129, 250 

realvariables 25, 27, 44, 58, 270, 
275-277 

RECALL statement 110,298 

REDIM’D ARRAY error 79,250 

REENTER message 99, 100 

relational operators 33, 54, 82 

REM statement 7,229,267 

reserved words 27, 245-246, 276 

key 16 

reset vector 16 

restarting the system 96, 112, 176, 
181 

RESTORE statement 106, 108, 
229, 250 

Restoring Normal Error Handling 
71 

RESUME statement 69, 70, 229, 
249, 265 

return address 63, 66, 227 

[RETURN | key 4,6, 10, 13, 16, 18, 
100, 104, 158, 165, 219, 241, 293 
INPUT statementuse 97,98 

RETURN statement 61ff, 220, 227, 
251 
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RETURN WITHOUT GOSUB 


error 64,67, 251 
right bracket (1) 4, 16, 119, 247 
RIGHT function 100, 229, 249 
RIGHT-ARROW) key 18, 19, 241 
FND function 43,229 
ROT= statement 160, 164, 230 
rotation 230 
rounding 39 
RTS (Return From Subroutine) 174 
RUN Command 12, 14, 30, 108, 
145, 150, 230, 294 





Ss 


SAVE Command 13, 131, 230, 297 

scale factor 230 

SCALE= statement 160, 163, 164, 
230 

scientific notation 43,91, 118, 283 

SCRN function 141,231 

scrolling 253 

seeding 43 

semicolon(s) 113ff, 122, 267, 269 

SGN function 39, 231 

shape definition 150 

shape table(s) 150ff, 230, 231, 234, 
299 
index 153 
loading 154ff 

SHLOAD statement 110, 156, 158, 
165, 231, 299 

signofanumber 39, 231 

simple variables 275-277 

SIN function 40, 231 

sine 40, 231 

slash(/) 296 

soft switches 253, 259 

key 110, 262 

space bar 19, 21 

space character 99, 101, 105, 231 

SPC function 113, 120-121, 231, 
249 

speaker 130, 264 

SPEED statement 128, 231 

SQR function 40, 232, 249 

square root 40, 232 

statements 3, 223, 269 
see also names of statements 

step value 5/7ff 

stepwise refinement 189 

STOP statement 17, 73,216 

STR# function 89, 232 

string(s) 28, 81, 113, 229, 232, 233, 
270, 275ff, 293, 295 
comparison 82 








constants 28, 81,83 
conversion 89 
input 99 
null 28 
pointers 275-277 
storage 179 
variables 26, 28, 44, 83, 102, 
104, 105, 107 
STRING TOO LONGerror 84, 
85, 114, 251 
subroutine(s) 10, 61ff, 171, 229, 
250, 269, 270, 276 
call 61 
execution 220 
nested 62 
subscripts 29, 77, 79 
substrings 86, 295 
subtraction 32,36 
syntax definitions 235ff 
syntax error 13, 14, 54, 58, 105, 
107, 143ff, 166, 251 


T 


TAB function 113, 120, 121ff, 126, 
181, 232, 249, 254 

TAN function 41,233 

tangent 41, 233 

tape cassette 13, 14, 110, 156, 158, 
165, 228, 230, 231, 297ff 

termination 218, 232 

text 142,253 
window 115, 119ff, 129, 136, 143, 

221, 253ff 

TEXT statement 119, 136, 1483, 
230, 200 

TRACE command 180, 181, 226, 
233, 294 

trigonometric functions 40-41 

true 33ff 

truncation 28, 39,51, 65, 86, 88, 
91,117, 120ff, 283 

TYPE MISMATCHerror 87, 88, 
251 


U 


unconditional branch 50, 220 

UNDEF ’D FUNCTIONerror 251 

UNDEF ‘’D STATEMENT error 12, 
50,51, 64, 251, 268 

[UP-ARROW | key 18, 19, 241 

user-defined function 44-45 

USR function 172,233 

utility strobe 131, 261, 264 
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VAL function 83, 86, 90, 102, 105, 
107, 233 
validation of data 187 
values, logical 33,54 
variable(s) 25ff, 51,97, 98, 177, 
216, 268 
argument 44 
index 55,57, 58, 60 
integer 26 27, 44, 58 
name 26,293 
real 25, 27, 44, 58, 270, 275ff 
string 26, 28, 44, 102, 105 
WLINstatement 140, 234 
TAB statement 119, 120, 124, 
181, 234, 256 


WwW 


WAIT statement 174, 234, 249 
wraparound 4, 120, 122 


X 


XDRAW statement 151, 161ff, 230, 
231, 234 
XPLOT statement 246 


Y 


Zz 
zeropage 2/78 


Cast of Characters 


" (double quotation marks) 28, 81, 
99, 102, 270 
#£ (numbersign) 96, 111, 180, 246 
* (dollarsign) 26, 29, 82, 88, 251, 
259 
(percent character) 26, 28 
(ampersand) 246 
() (parentheses) 37, 250, 276 
(asterisk) 31,32 
(plus sign) 31,36, 84, 105 
(comma) 98ff, 105, 113*ff 
(minus sign) 31,36, 105 
» (period) 105 
/ (slash) 31,296 
(colon) 5, 98ff, 105, 106, 177, 192, 
246, 267, 296, 301 
; (semi-colon) 113ff, 122, 267, 269 
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fo + -F ook 





“= (lessthan) 34 
“=or=< (lessthanorequalto) 34 
= (equalsign) 30, 34, 44, 129, 137, 
145, 163, 246 
* (greaterthan) 34 
*=Or= (greater than or equal to) 34 
#>or?4 (notequalto) 34 
? (question mark) 97, 116, 294 
] (right bracket) 4, 16, 119, 247 
\ (backslash) 4, 18 
(caret) 31 
80-Column Text Card 4, 112ff, 119, 
124, 125, 127, 222, 254, 287ff 
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